═══ 1. Trademarks and Service Marks ═══ The following terms used in this documentation are trademarks or service marks of IBM Corporation in the United States and other countries:  C Set ++  IBM  Operating System/2  OS/2  VisualAge  WorkFrame ═══ 2. Introducing the Performance Execution Trace Analyzer ═══ The IBM VisualAge C++ for OS/2, V3.0 Performance Execution Trace Analyzer is an application that helps you understand and improve the behavior of IBM C and C++ programs. The Performance Analyzer traces the execution of a program and creates a trace file. The trace file contains trace analysis data that can be displayed in diagrams. Using these diagrams, you can improve the performance of a program, examine occurrences that produce faults, and in general, understand what happens when a program runs. The Performance Analyzer does not replace static analyzers or debuggers, but it can complement them by helping you understand aspects of the program that would otherwise be difficult or impossible to see. For instance, with the Performance Analyzer you can: Time and tune programs The Performance Analyzer time stamps each trace event using a high resolution clock (about 838 nanoseconds per clock tick). As a result, the trace file contains a detailed record of when each traced function was called and when it returned. The trace data also shows how long each function runs, which helps you find hot spots. Locate program hangs and deadlocks The Performance Analyzer provides a complete history of events leading up to the point where a program stops. You can view the function call stack from anywhere in the program. Trace multithreaded interactions When multithreaded programs are traced, you can look at the sequencing of functions across threads in some of the diagrams. This highlights problems within critical areas of the program. Related Information  Preparing Your Program for the Performance Analyzer  Starting the Performance Analyzer from OS/2  Starting the Performance Analyzer from WorkFrame  Creating a Trace File. ═══ 2.1. New and Enhanced Features ═══ Performance Analyzer - Window Manager window The Performance Analyzer - Window Manager window is the control window for the Performance Analyzer. From this window, you can start most Performance Analyzer functions. For instance, you can:  Start creating a new trace file  Start analyzing an existing trace file  Open and close a diagram. Trace On and Trace Off push buttons These buttons, which appear on the Application Monitor window, let you start and stop the trace of your program. In addition, you can add calls to PerfStart and PerfStop in your source code to start and stop gathering events at precise moments during program execution. WorkFrame integration If you have started the Performance Analyzer from WorkFrame, you can:  Display Help information for library functions, such as IBM Open Class functions, OS/2 system functions, and C runtime functions.  Start the WorkFrame editor from a Performance Analyzer diagram and edit your source code.  Start other programs from the Performance Analyzer. Tracing capability in dynamic link libraries In addition to tracing functions in the executable file, the Performance Analyzer can trace your program's activity in:  Statically or dynamically linked Dynamic link libraries (DLLs).  The following system libraries: - DOSCALL.DLL - PMGPI.DLL - PMWIN.DLL  Dynamically linked load-on-call DLLs. If you only want to trace a load-on-call DLL, the Trace Generation window will not have any executables or DLLs listed in the window, and you will receive an informational message. Tracing capability for up to 64 threads The Performance Analyzer can trace up to 64 threads. The diagrams show activity on all or selected threads. Pop-up menus Clicking mouse button two in most diagrams displays pop-up menus that let you quickly access frequently used functions. Time find capability in Call Nesting The Call Nesting diagram has a search capability that lets you go to specific times in the trace file. Time Line diagram The Performance Analyzer can display user events in the Time Line diagram. Status Area Each diagram has a Status Area, which shows you detailed information about the trace file data. Vertical Ruler Many diagrams have a Vertical Ruler that shows your location in the trace file. Related Information  Preparing Your Program for the Performance Analyzer  Starting the Performance Analyzer from OS/2  Starting the Performance Analyzer from WorkFrame  Creating a Trace File  Performance Analyzer - Window Manager Window  Trace On Push Button  Trace Off Push Button  Starting and Stopping the Performance Analyzer from Your Program.  Tracing Dynamic Link Libraries (DLLs). ═══ 3. Preparing Your Program for the Performance Analyzer ═══ Before you create a trace file and begin using the Performance Execution Trace Analyzer, you must compile and link your program with the proper options. This is described in Compiling and Linking Your Program. The Performance Analyzer provides several ways to customize trace files. If you want to customize a trace file, you may have to complete some steps before you compile and link your program. For more information and instructions, see the following topics:  Tracing Dynamic Link Libraries (DLLs)  Tracing System Calls  Creating User Events in Your Program  Starting and Stopping the Performance Analyzer from Your Program. ═══ 3.1. Compiling and Linking Your Program ═══ You must compile and link your program with the proper options before you create a trace file and analyze it with the Performance Analyzer. The Performance Analyzer provides several ways to customize trace files. If you want to customize a trace file, you may have to complete some steps before you compile and link your program. For more information and instructions, see the following topics:  Tracing Dynamic Link Libraries (DLLs)  Tracing System Calls  Creating User Events in Your Program  Starting and Stopping the Performance Analyzer from Your Program. Compiling When compiling your program, use the following options: /Gh Includes the profile hooks that allow the Performance Analyzer to monitor your executable. /Ti Includes debugging information in the compiled object file. Linking You must link the CPPOPA3.OBJ object file into your program. When linking your program, use the following options: /DE Instructs the linker to include debug information in the executable (EXE) or dynamic link library (DLL) file. /NOE Instructs the linker not to search for symbols in the extended dictionaries of the libraries being linked. Example The following example shows how to compile and link a program called SAMPLE.EXE for use with the Performance Analyzer. The required object file is highlighted in bold. Compile: icc /c /Ti /Gh sample.c Link: icc /b"/DE /NOE" /FeSAMPLE.EXE sample.obj cppopa3.obj Related Information  IBM C/C++ Tools: Programming Guide  Tracing Dynamic Link Libraries (DLLs)  Tracing System Calls  Creating User Events in Your Program  Starting and Stopping the Performance Analyzer from Your Program. ═══ 3.2. Tracing Dynamic Link Libraries (DLLs) ═══ You can trace statically or dynamically linked DLLs and load-on-call DLLs using the Performance Analyzer. Compile and link any DLL to be traced for use by the Performance Analyzer as explained in Compiling and Linking Your Program. You can trace DLLs without tracing the main program that calls the DLLs. The tracing of load-on-call DLLs occurs automatically; it cannot be suppressed. Also, you cannot set triggers, or enable or disable functions in dynamically linked DLLs. ═══ 3.3. Tracing System Calls ═══ If you want to trace calls into the OS/2 Toolkit Application Programming Interface (API), specify the following Performance Analyzer libraries before the OS/2 libraries in your link statement. You can link one or more libraries. This is shown in the Example under Compiling and Linking Your Program. If you want to trace file accesses, you must link the _DOSCALL.LIB library. Notes  Output produced by cout stream objects is stored in the operating system's buffer and is not shown until tracing has stopped, and DosCalls for these calls are not displayed in the trace file.  It is not possible to trace events in the DOSCALL intercept library only. The Performance Analyzer looks for at least one event from your program before logging DOS call events. If you link the _DOSCALL.LIB library, compile your program with the /Gh option to include events from your program in the trace file. The APIs and their corresponding Performance Analyzer libraries are as follows. Each library listed also has an associated DLL. API Library DosCalls _DOSCALL.LIB WinCalls _PMWIN.LIB GpiCalls _PMGPI.LIB Important The order in which these libraries are specified in the link statement is critical. If the replacement libraries do not precede the OS/2 libraries in the link statement, the Performance Analyzer will not interpret and trace the API calls. Related Information  Compiling and Linking Your Program  Tracing File Accesses  IBM C/C++ Tools: Programming Guide. ═══ 3.4. Creating User Events in Your Program ═══ The CPPOPA3.OBJ file contains an entry point called PERF that accepts calls from the program you are tracing. Calls to the PERF entry point at run time are referred to as user events. User events cause text strings to be inserted into the trace file. To add a call to the PERF entry point: 1. Declare a prototype for the PERF entry point. If you add a user event to your program source file, you must also include a prototype for the PERF entry point. For C and C++ programs, the prototype will be inserted for you when you compile your program if you place the following statement at the beginning of your source file: #include Note: If you want to insert the prototype yourself, the prototypes for C and C++ programs are as follows: C Prototype VOID PERF (PSZ string); C++ Prototype EXTERN "C" {VOID PERF(PSZ string);} 2. Add a call to the entry point everywhere you want a user event generated. The following is an example of a call to the PERF entry point: PERF (string); where: string is an ASCIIZ string. When such a call is made, the string is placed in the trace file. You can see the string in the Call Nesting Statistics, and Time Line diagrams. Warning:  The string must consist of unique, static, alphanumeric characters. Otherwise, you will receive unpredictable results.  The string must exist in storage when your program terminates. If the string exists in automatic storage on the stack or storage defined in a dynamically loaded DLL, the string will appear in the trace file, but the text may not appear as it was defined. (The string can be allocated on the heap if its contents are not deleted when your program terminates.) Related Information  Compiling and Linking Your Program  Tracing System Calls  Starting and Stopping the Performance Analyzer from Your Program  Annotate Window  Call Nesting diagram  Statistics diagram  Time Line diagram  Application Monitor Window  IBM C/C++ Tools: Programming Guide. ═══ 3.5. Starting and Stopping the Performance Analyzer from Your Program ═══ The CPPOPA3.OBJ file contains entry points called PerfStart and PerfStop that accept calls from the program you are tracing. Calls to the PerfStart and PerfStop entry points cause the Performance Analyzer to start and stop tracing, respectively. By putting these calls into your source code, you can control precisely when the Performance Analyzer starts and stops recording events during program execution. To turn tracing:  On, call the PerfStart entry point.  Off, call the PerfStop entry point. Notes: 1. If the trace is already on, calling PerfStart has no effect. If the trace is already off, calling PerfStop has no effect. 2. You can also start and stop tracing with the Trace on and Trace off push buttons on the Application Monitor window. You can place calls to the PerfStart and PerfStop entry points anywhere in your program, even in different functions, object modules, or DLLs. To add calls to the PerfStart and PerfStop entry points: 1. Declare a prototype for the PerfStart and PerfStop entry points. For C and C++ programs, the prototypes will be inserted for you when you compile your program if you place the following statement at the beginning of your source file: #include Note: If you want to insert the prototypes yourself, the prototypes for C and C++ programs are as follows: C Prototype VOID PerfStart (VOID); VOID PerfStop (VOID); C++ Prototype EXTERN "C" {VOID PerfStart (VOID);} EXTERN "C" {VOID PerfStop (VOID);} 2. Add a call to the appropriate entry point everywhere you want to start or stop tracing. The following example shows how calls to the PerfStart and PerfStop entry points could be placed in your program: . . . PerfStop(); // turn off tracing here . . . PerfStart(); // resume tracing here Related Information  Compiling and Linking Your Program  Tracing System Calls  Annotate Window  Call Nesting diagram  Statistics diagram  Time Line diagram  Application Monitor Window  IBM C/C++ Tools: Programming Guide. ═══ 4. Starting the Performance Analyzer from OS/2 ═══ After completing the instructions in Preparing Your Program for the Performance Analyzer, you are ready to create a trace file and use the Performance Analyzer to analyze your program. The command you enter to start the Performance Execution Trace Analyzer depends on which of the following you want to do first:  Trace an executable  Analyze an existing trace file.  Display the Performance Analyzer's main control window Tracing an Executable  If you have an executable you want to trace, you can start the analyzer from an OS/2 command prompt or a command file (.CMD) by entering: icsperf myprog parms Where: myprog Represents an executable file name. This is optional. parms Represents executable parameters. These are optional. Note: The first time you start the Performance Analyzer, a profile window appears and prompts you to specify where the Performance Analyzer's profile file should be located. If you want the default, press the OK push button. See Performance Analyzer - Specify Profile Location Window for more information.  You can also include the /go option in the command: icsperf /go myprog parms Where: /go Option that executes your program, creates a trace file, and then exits the Performance Analyzer. This option is useful if you have several programs (requiring no manual intervention) that you want to run in succession from an OS/2 command file. This is optional. myprog Represents an executable file name. parms Represents executable parameters. These are optional. Analyzing an Existing Trace File If you want to start analyzing a trace file you have already created, you can start the analyzer from an OS/2 command prompt or a command file (.CMD) by entering: icsperf /x myprog.trc Where: /x Represents one or more of the following analyzer options. If you have already created a trace file, these options cause the trace file to be displayed in their respective diagrams. Once you are familiar with the Performance Analyzer application, you can quickly open the diagrams by entering as many of these options as you want in your startup command. This is optional. /cn Displays the trace file in the Call Nesting diagram. /ed Displays the trace file in the Execution Density diagram. /cg Displays the trace file in the Dynamic Call Graph. /ss Displays the trace file in the Statistics diagram. /tl Displays the trace file in the Time Line diagram. myprog.trc Represents a trace file name. Displaying the Performance Analyzer's Main Control Window If you enter the following command, the analyzer's main control window, the Performance Analyzer - Window Manager window, appears: icsperf From this window, you can start either tracing an executable or analyzing an existing trace file. See Creating a Trace File to continue. To analyze WorkPlace Shell objects: 1. Replace the RUNWORKPLACE line in your config.sys file with the following line: SET RUNWORKPLACE=C:/OS2/CMD.EXE 2. Restart your system. 3. At an OS/2 prompt, type the following: icsperf c:/os2/pmshell Related Information  Introducing the Performance Analyzer  Preparing Your Program for the Performance Analyzer  Performance Analyzer - Window Manager Window  Creating a Trace File  Analyzing a Trace File ═══ 5. Starting the Performance Analyzer from WorkFrame ═══ Before you start the Performance Analyzer from the WorkFrame environment, you must: 1. Create a project for the program you want to analyze. Note: For information on creating a project, refer to your WorkFrame documentation. 2. Compile and link your program with Performance Analyzer options. Note: This is described in Compiling and Linking Your Program. 3. Open a project folder in the WorkFrame window. 4. Highlight an object that represents an executable file or a trace file. 5. Click mouse button two on the highlighted object to display a pop-up menu. 6. Select Analyze. Related Information  Introducing the Performance Analyzer  Preparing Your Program for the Performance Analyzer  Performance Analyzer - Window Manager Window  Creating a Trace File  Analyzing a Trace File  Search Paths... Choice  Project Menu  Exiting the Performance Analyzer. ═══ 6. Exiting the Performance Analyzer ═══ If you want to exit the Performance Analyzer, and are not in the process of creating a trace file, do the following: 1. Select the Exit the Performance Analyzer choice from one of the following menus:  File menu on the Performance Analyzer - Window Manager window  Application menu on the Trace Generation window  Trace file menu on any of the diagrams. 2. Select Yes when prompted. If you want to exit the Performance Analyzer while a trace file is being created, do the following: 1. Click on the Stop push button on the Application Monitor window. 2. Click on the Cancel push button on the Analyze Trace window. 3. Select the Exit the Performance Analyzer choice from the File menu on the Performance Analyzer - Window Manager window. 4. Select Yes when prompted. Related Information  Performance Analyzer - Window Manager Window  Quick Exit Choice  Exit the Performance Analyzer Choice. ═══ 7. Creating a Trace File ═══ After compiling and linking your program, you can start the Performance Analyzer and create a trace file. A trace file contains a chronological sequence of events that occur during the execution of your program. By analyzing the trace file, you can learn about your program's structure, locate and diagnose problems, and pinpoint ways to improve performance. The Performance Analyzer provides five diagrams in which you can analyze the trace file. Each diagram presents a different view of the trace file to give you an overall idea of how your program performs. The diagrams are as follows:  Call Nesting  Dynamic Call Graph  Execution Density  Statistics  Time Line. Note: Before creating a trace file, you must prepare your program for use by the Performance Analyzer. For more information, see Preparing Your Program for the Performance Analyzer. To create a trace file: 1. Click on the Create Trace... push button in the Performance Analyzer - Window Manager window. 2. Type the full path name and the file name of the program you want to trace in the Program Name entry field. If the program is in your current directory, you do not have to type the path name. Note: If you are not sure where the file is located, select the Find... push button. 3. Type any parameters that you want to pass to your program in the Program Parameters entry field. Note: This entry field is optional. 4. If you want the trace file to have a different path or file name than the defaults, type a path and file name in the Trace File Name entry field. The default path name is the directory where your program resides. The default trace file name is myprog.trc, where myprog is the name of the program you are tracing. Note: This entry field is optional. 5. Type any comments that you want to make about your trace in the Trace File Description entry field. Note: This entry field is optional. 6. Select the OK push button. The Trace Generation window appears. 7. Select the Trace push button in the Trace Generation window. Your program begins executing. When your program ends, the Analyze Trace window is displayed. 8. Click on the check box next to each diagram in which you want to view the trace file. Related Information  Compiling and Linking Your Program  Create Trace Window  Trace Generation Window  Analyze Trace Window. ═══ 8. Creating a Customized Trace File ═══ By default, the Performance Analyzer generates event information for every function possible. However, this sometimes causes the trace file to become large and difficult to manage. You can limit the size of your trace file by changing the parameters that control its size prior to running your program. The following parameters affect the size of the trace file:  Enabled or disabled state of components  Call depth setting for each thread  Time stamp setting  File access setting  Trigger settings. You can also customize the trace file by:  Disabling buffer flushing or changing the buffer size setting to specify how often the buffer flushes to the trace file. For more information, see Changing the Buffer Size and Buffer Control Window.  Giving the trace file a file name other than the default. The default file name is myprog.trc, where myprog is the name of the program you are tracing. For more information on specifying a different trace file name, see Name Trace File... Choice or Unique Trace File Name Choice.  Attaching a description to the trace file. A description can make a trace file easier to identify, especially when you create more than one trace file from the same program and use different options for each trace. The description is displayed in the Status Area of any open diagram. For more information on attaching a description to a trace file, see Name Trace File... Choice or Unique Trace File Name Choice. Related Information  Preparing Your Program for the Performance Analyzer  Compiling and Linking Your Program  Performance Analyzer - Window Manager Window  Trace Generation Window. ═══ 8.1. Enabling and Disabling Components ═══ From the Edit menu in the Trace Generation window, you can control which parts of your program are traced by enabling and disabling components. A component can be an executable file, dynamic load library (DLL) file, an object (OBJ) file, or a function. EXE and DLL files contain object files, and object files contain functions. To view or hide components in the window, click on the plus and minus icons to expand and contract EXE, DLL, and OBJ files. When a component is enabled, data for that component will be included in the trace file when the component is executed. When the component is disabled, no data is recorded in the trace file when the component is executed. Note: The Performance Analyzer's default is to enable all components that have been compiled and linked with the proper options. When you disable:  An EXE, DLL, or OBJ file, the Performance Analyzer disables all functions within the selected file and removes any triggers set on functions within the file.  A function, the Performance Analyzer removes any trigger set on it. When you enable:  An EXE, DLL, or OBJ file, the Performance Analyzer enables all functions within the selected file. When you set a trigger on a disabled function, the Performance Analyzer enables the function. The following choices are available from the Edit menu on the Trace Generation window. The choices displayed in the menu change depending upon the type of component selected; therefore, all of the choices are not displayed at the same time. Enable all executables Enables all functions in all executable files. Disable all executables Disables all functions in all executable files. Enable executable Enables all functions in a selected executable file. This choice is available when you select a disabled executable. Disable executable Disables all functions in a selected executable file. This choice is available when you select an enabled executable. Enable object file Enables all functions in a selected object file. This choice is available when you select a disabled object file. Disable object file Disables all functions in a selected object file. This choice is available when you select an enabled object file. Enable function Enables a function. This choice is available when you select a disabled function. Disable function Disables a function. This choice is available when you select an enabled function. Set trigger Sets a trigger on a function so that the Performance Analyzer traces the function and its associated calls. This choice is available when you select a function that does not have a trigger set on it. Note: If triggers are set, the Performance Analyzer traces all enabled components and only those functions on which triggers are set. If no triggers are set, the Performance Analyzer traces all enabled components. Remove trigger Removes a trigger on a function so that the Performance Analyzer does not trace the function and its associated calls. This choice is available when you select a function that has a trigger set on it. Note: If triggers are set, the Performance Analyzer traces all enabled components and only those functions on which triggers are set. If no triggers are set, the Performance Analyzer traces all enabled components. You can enable or disable a component in one of the following ways:  Click on the file name or icon of the component you want to enable or disable. Then select the appropriate enable or disable choice from the Edit menu on the Trace Generation window.  Double-click on the file name or icon of the component you want to enable or disable.  Click mouse button two on the file name or icon of the component you want to enable or disable. Then select the appropriate enable or disable choice from the pop-up menu. Note: If the icon next to a component is:  Green (it also has no slash mark), the component is enabled.  Red (it also has a slash mark), the component is disabled.  White, the component cannot be traced. ═══ 8.2. Selecting the Call Depth for Each Thread ═══ Select Call depth... from the Options menu on the Trace Generation window to select the number of calls you want to trace or to specify threads you want to include or exclude from the trace file. When the Call Depth window is displayed, you can select as many as 64 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. You may want to limit the call depth to isolate an area of interest and reduce the amount of trace data. Related Information  Call Depth... Choice  Trace Generation Window  Keys Help. ═══ 8.3. Using Time Stamps ═══ Select Time stamp events from the Options menu on the Trace Generation window to choose whether to time stamp events during the trace analysis. The Performance Analyzer uses an internal timer to get high resolution time stamps. While logging events, the Performance Analyzer adds a small amount of overhead time to the normal runtime speed of the program. The time added is negligible, so you may not be able to tell the difference between code that has been traced and code that has not, even for highly interactive programs. The overhead time added by the Performance Analyzer is not shown in the times reported for user code in all of the Performance Analyzer diagrams. the Performance Analyzer time stamps the buffer flush so that the buffer-flushing overhead can be removed from the diagrams. If you choose to create a trace file without time stamps, you can only view it in the Dynamic Call Graph and the Call Nesting and Statistics diagrams. Related Information  Time Stamp Events Choice  Understanding Overhead Time  Trace Generation Window  Keys Help. ═══ 8.4. Tracing File Accesses ═══ When a DOS call references a file, the Performance Analyzer keeps track of the file name associated with the traced DOS call. These calls are shown in the diagrams under the functions that made the file accesses. They appear as function names with their corresponding files in parentheses. The Performance Analyzer can trace file access calls that use the following DOS calls:  DosOpen()  DosRead()  DosWrite()  DosClose()  DosDupHandle()  DosResetBuffer()  DosSetFilePtr()  DosSetFileLocks()  DosSetFileSize()  DosQueryFileInfo()  DosQueryHType() To set file access:  Select the File access choice from the Options menu on the Trace Generation window. A check mark appears next to the choice to indicate that the choice is enabled. To reset file access:  Select the File access choice from the Options menu on the Trace Generation window. The check mark is removed to indicate that the choice is disabled. Notes:  The settings you enter are saved for the current session. If you want to save the settings for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu.  You can only select the File access choice when the _DOSCALL.LIB file is linked with your program. Related Information  Trace Generation Window  Keys Help. ═══ 8.5. Setting and Removing Triggers ═══ A trigger turns tracing on when it is called and then turns tracing off when it returns. The Performance Analyzer allows you to set and remove triggers on functions. You can set multiple triggers. By setting triggers to start or stop tracing at selected points in your program, you can control the size of your trace file. You can set and remove triggers from the Edit and Function pop-up menus on the Trace Generation window. Remember the following when using triggers:  If triggers are set, the Performance Analyzer traces all enabled components and only those functions on which triggers are set. If no triggers are set, the Performance Analyzer traces all enabled components.  If a trigger function is nested within another trigger function, tracing is turned off only after the outer function returns.  A function that has a trigger set on it has the letter T in the icon next to its function name in the Trace Generation window.  If you disable an EXE, DLL, or object (OBJ) file, the Performance Analyzer disables all functions within the selected file and removes any triggers set on functions within the file.  If you set a trigger on a disabled function, the Performance Analyzer enables the function.  If you disable a function, the Performance Analyzer removes any trigger set on it. Related Information  Set Trigger Choice  Remove Trigger Choice  Function Pop-up Menu  Keys Help. ═══ 8.6. Changing the Buffer Size ═══ Select Buffer Control from the Options menu on the Trace Generation window to change the buffer size or to enable buffer wrapping. During a trace analysis, the Performance Analyzer and your program share memory with the trace buffer. The trace buffer allows the Performance Analyzer to log events that are running in the address space of the program. When the trace buffer is full, the Performance Analyzer: 1. Stops the program 2. Time stamps the start of the buffer flush 3. Writes the events in the buffer to the trace file 4. Time stamps the end of the buffer flush 5. Restarts the program. Note: Time stamping the buffer flush allows the diagrams to remove the buffer-flushing overhead time. You can select the size of the trace buffer, and thereby change the time spent flushing the buffer to the trace file. When you increase the size of the buffer, more events are recorded before the Performance Analyzer flushes the buffer. Likewise, when you decrease the size of the buffer, fewer events are recorded before the Performance Analyzer flushes the buffer. You can also enable buffer wrapping, which causes the Performance Analyzer to overwrite older events in the buffer with newer ones. Since the buffer is flushed only when the program ends, less disk space is needed for the trace file, but some trace data is lost. The default for buffer wrapping is disable. For more information on disabling buffer wrapping, see Buffer Control Window. Related Information  Buffer Control Window  Trace Generation Window  Keys Help. ═══ 8.7. Naming the Trace File ═══ Select Name trace file... from the Options menu on the Trace Generation window. In the Name Trace File window, you can enter your own trace file name and a short description. The default file name is myprog.trc, where myprog is the file name of the program you are tracing. When you run several traces of the same program, this option lets you name each trace file and describe what you did differently for each trace. For example, if you disable an object file for the first trace and disable time stamps for the second trace, you could name the first trace file TRACE1 and enter Disabled object file for its description. Likewise, you could name the second trace file TRACE2. and enter Disabled time stamps for its description. A trace file's description is displayed in the Status Area of any open diagram. Related Information  Name Trace File... Choice  Trace Generation Window  Keys Help. ═══ 8.8. Saving Trace File Settings ═══ Trace settings (settings that determine how your program is traced) that you enter are saved for the current session. You can save some trace settings for subsequent traces. If you want to save settings for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Save Choice  Trace Generation Window  Keys Help. ═══ 9. Analyzing a Trace File ═══ After you have created your trace file, the Performance Analyzer provides five diagrams in which you can view and analyze the data. Each diagram presents a different view of the trace file to give you an overall idea of how your program performs. The following list contains a description of each diagram and shows the icon that represents it in the Performance Analyzer - Window Manager window when the diagram is open. Diagram/Icon Description Call Nesting Shows the flow of control and interactions among the various threads. Use this diagram to diagnose problems with critical sections, sequencing protocols, thread delays, and program deadlocks and crashes. Dynamic Call Graph Shows overall view of program and the flow of the program. You can easily see where the most time was spent. Execution Density Shows the program by execution time and assists in determining the trends of the functions. Statistics Provides a textual report of execution time by function or executable. You can use this diagram to find hot spots in the overall execution. You can also use this diagram to determine which user functions to inline. Time Line Places the function calls and returns in sequence along a time line. To open a trace file in any diagram, use any of the following methods:  Click on the Analyze Trace... push button in the Performance Analyzer - Window Manager window, and then, in Analyze Trace window, enter a trace file name and select one of the diagram check boxes.  Double-click on the file name or icon of a trace file in the Performance Analyzer - Window Manager window, then select one of the diagram check boxes in the Analyze Trace window.  Click mouse button two on the file name or icon of a trace file in the Performance Analyzer - Window Manager window, then select a diagram from the Trace File pop-up menu.  From the Trace File menu of an open diagram, select Open as and then select a diagram from the cascaded menu. Related Information  Selecting a Trace File to Analyze  Performance Analyzer - Window Manager Window  Analyze Trace Window  Trace File Pop-up Menu  Selecting Functions to Inline  Hints for Using the Performance Analyzer. ═══ 9.1. Selecting a Trace File to Analyze ═══ You select a trace file to analyze from the Analyze Trace window. Complete these steps to select a file: 1. Click on the Analyze Trace... push button in the Performance Analyzer - Window Manager window. The Analyze Trace window appears. 2. Type the full path name and file name of the trace file you want to analyze in the Trace file name entry field. If the program is in your current directory, you do not have to type the path name. Note: If you are not sure where the file is located, select the Find... push button. 3. From the Diagrams group heading, select a diagram in which you want to view the trace file by clicking on the check box next to the diagram name. You can select one or more of the following diagrams:  Call Nesting  Dynamic Call Graph  Execution Density  Statistics  Time Line. 4. Select OK. Related Information  Analyzing a Trace File  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistical Summary Diagram  Time Line Diagram  Creating a Trace File. ═══ 9.2. Understanding Overhead Time ═══ When you compile and link your program, the compiler generates hooks that enable the Performance Analyzer to intercept trace events. The time at which each trace event executes is recorded in the trace file. These hooks cause a small monitoring function to be called instead of the program's callee function. The monitoring function time stamps the event and then calls the program's callee function. The monitoring function is run in the program's address space, thereby avoiding the high overhead of an operating system context switch when events are recorded. As a result, it does not significantly affect the program's runtime performance. However, the monitoring function does take some small amount of time to execute. In order to compensate for this additional time introduced by the monitoring function, the diagrams adjust the timings appropriately. The Performance Analyzer dynamically determines how much time it takes to execute the monitoring function by internally calling it several times and computing an average prior to executing the program. As a result, it is recommended that you shut down other programs on your desktop so they will not interfere with the Performance Analyzer's timings. If the program is run stand-alone, events are not recorded and should run at or near the same speed as the same program compiled without the profile hooks. Related Information  Introducing the Performance Analyzer  Creating User Events in Your Program  Starting and Stopping the Performance Analyzer from Your Program  Tracing System Calls  Compiling and Linking Your Program  Starting the Performance Analyzer from OS/2  Starting the Performance Analyzer from WorkFrame  Performance Analyzer - Window Manager Window. ═══ 9.3. Selecting Functions to Inline ═══ Your trace file can help you determine which functions to inline. To do this: 1. In addition to preparing your program for the Performance Analyzer as described in Compiling and Linking Your Program, include the /Oi compiler option, which causes user functions to be inlined. 2. Create a trace file and display it in the Statistics diagram. Note: Functions that appear in the Statistics diagram were not inlined. If an inlined function appears in the Statistics diagram, the compiler chose not to inline it. 3. Look for functions in the Statistics diagram that were called frequently and had small average executable times. These functions may be good candidates for inlining. Related Information  Compiling and Linking Your Program  Statistics Diagram  IBM C/C++ Tools: Reference Summary  Keys Help. ═══ 10. Performance Analyzer - Specify Profile Location Window ═══ When you start the Performance Analyzer for the first time, the Performance Analyzer - Specify Profile Location window appears. This window prompts you to type the path name where you want to store the ICSPERF.INI file. The ICSPERF.INI file stores your session settings. The default path name is the drive and directory where your OS/2 operating system is installed. If you want to store the ICSPERF.INI file in a drive and directory other than the default, type the full path name in the Path entry field, and then select OK. The ICSPERF.INI file is created in the directory you specified. Related Information  Introducing the Performance Analyzer.  Preparing Your Program for the Performance Analyzer ═══ 11. Performance Analyzer - Window Manager Window ═══ The Performance Analyzer - Window Manager window is the Performance Analyzer's main control window and is always displayed while the Performance Analyzer is running. Once you have properly compiled and linked your program and started the Performance Analyzer, you can start most functions from this window, including creating and analyzing trace files. When you view a trace file, this window lists the file names of your executable, its trace file, and each open diagram. Areas of the Performance Analyzer - Window Manager Window  Menu Bar Summary - File - View - Options - Project (only available when working in the WorkFrame environment) - Help  Pop-up Menus - Executable - Trace file - Diagram  Push Buttons - Create Trace... - Analyze Trace.... Related Information  Introducing the Performance Analyzer  Compiling and Linking Your Program  Creating a Trace File  Selecting a Trace File to Analyze  Exiting the Performance Analyzer  Keys Help. ═══ 11.1. Performance Analyzer - Window Manager Window File Menu ═══ The Performance Analyzer - Window Manager window File menu has the following choices: Create Trace... Displays the Create Trace window, which lets you start creating a trace file for your program. Analyze Trace... Displays the Analyze Trace window, which lets you open a diagram and start analyzing your program. Exit Performance Analyzer Lets you end the Performance Analyzer application. Related Information  Compiling and Linking Your Program  Executable Pop-up Menu  Trace File Pop-up Menu  Diagram Pop-up Menu  Create Trace Window  Analyze Trace Window  Keys Help  Exiting the Performance Analyzer  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.1.1. Create Trace... Choice ═══ Select the Create trace... choice to start creating a trace file. This choice is available from the File menu on the Performance Analyzer - Window Manager window. Note: Before creating a trace file, you must compile and link your program with the proper options. When you select this choice, the Create Trace window appears. On the Create Trace window, specify the program you want to trace and any parameters you want to pass to the program. You can also display the Create Trace window by:  Clicking mouse button two on an executable file name or icon, , in the Performance Analyzer - Window Manager window, and then selecting Create trace... from the Executable pop-up menu.  Clicking on the Create Trace... push button in the Performance Analyzer - Window Manager window. Related Information  Compiling and Linking Your Program  Create Trace Window  Creating a Customized Trace File  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.1.2. Analyze Trace... Choice ═══ Select the Analyze trace... choice to start analyzing an existing trace file. This choice is available from the File menu on the Performance Analyzer - Window Manager window. When you select this choice, the Analyze Trace window appears. On the Analyze Trace window, specify the diagrams in which you want to display and analyze the trace file. You can also display the Analyze Trace window by:  Clicking mouse button two on the file name or icon, , of a trace file in the Performance Analyzer - Window Manager window, and then selecting Analyze trace... from the Trace file pop-up menu.  Clicking on the Analyze Trace... push button in the Performance Analyzer - Window Manager window. Related Information  Compiling and Linking Your Program  Analyze Trace Window  Call Nesting Diagram  Dynamic Call Graph  Execution Density diagram  Statistics Diagram  Time Line Diagram  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.1.3. Exit the Performance Analyzer Choice ═══ Select the Exit the Performance Analyzer choice to end the Performance Analyzer application and close all associated windows. This choice is available from the File menu on the Performance Analyzer - Window Manager window. Related Information  Exiting the Performance Analyzer  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.2. Performance Analyzer - Window Manager Window View Menu ═══ The Performance Analyzer - Window Manager window View menu has the following choices: Tree lines Displays tree lines on the Performance Analyzer - Window Manager window. Show icons Displays icons that identify file types on the Performance Analyzer - Window Manager window. Remove all windows Removes and closes all open diagrams from your screen. Related Information  Introducing the Performance Analyzer  Selecting a Trace File to Analyze  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.2.1. Tree Lines Choice ═══ Select the Tree lines choice to display directory tree lines. This choice is available from the View menu on the Performance Analyzer - Window Manager window. A check mark next to this choice indicates that it is selected. To remove tree lines, select the choice again. The check mark is removed to show the choice is disabled. Note: The settings you enter are saved for the current session. If you want to save the settings for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.2.2. Show Icons Choice ═══ Select the Show icons choice to display icons that identify file types. This choice is available from the View menu on the Performance Analyzer - Window Manager window. A check beside this choice indicates that it is selected. To remove the icons, select the choice again. Icons identify file types as follows: Icon File Type Executable Trace file Call Nesting diagram Dynamic Call Graph Execution Density diagram Statistics diagram Time Line diagram Related Information  Introducing the Performance Analyzer  Selecting a Trace File to Analyze  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.2.3. Remove All Windows Choice ═══ The Remove all windows choice removes and closes all diagram windows displayed on your screen and diagram file names displayed in the Performance Analyzer - Window Manager window. This choice is available from the View menu on the Performance Analyzer - Window Manager window. Related Information  Introducing the Performance Analyzer  Selecting a Trace File to Analyze  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.3. Performance Analyzer - Window Manager Window Options Menu ═══ The Performance Analyzer - Window Manager window Options menu has the following choices: Font... Displays the Font window, which lets you change the font, font style, and font size for the windows. Quick exit Provides a fast way to exit the Performance Analyzer. Search paths... When you are working in the WorkFrame environment, this choice displays a window in which you can specify where the Performance Analyzer can locate source files for editing. Unique trace file name This choice gives each trace file a different name, which allows you to save several trace files created from the same program. Settings Displays a cascaded menu that lets you save settings or restore initial default settings. Related Information  Introducing the Performance Analyzer  Selecting a Trace File to Analyze  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.3.1. Font... Choice ═══ Select the Font... choice to change the font, font style, and font size for the text area on the Performance Analyzer - Window Manager window. This choice is available from the Options menu on the Performance Analyzer - Window Manager window. When you select this choice, the Font window appears. The Font window has the following areas: Name entry field Type a font name in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a name from the list. Size entry field Type a font size in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a size from the list. Style entry field Type a font style in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a style from the list. Emphasis check boxes Click on one of these check boxes to outline, underscore, or strikeout text. Sample box This box shows a sample of how text will appear with the settings you have selected. Ok push button Changes the font according to the settings you selected. Reset push button Changes all font settings to the default settings. Cancel push button Closes the window without making changes. Note: The settings you enter are saved for the current session. If you want to save the settings for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.3.2. Quick Exit Choice ═══ Select the Quick exit choice to close all open diagrams and exit the Performance Analyzer without a prompt to confirm that you want to exit the application. This choice is available from the Options menu on the Performance Analyzer - Window Manager window. Related Information  Introducing the Performance Analyzer  Selecting a Trace File to Analyze  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.3.3. Search Paths... Choice ═══ When you are working in the WorkFrame environment, select the Search paths... choice to specify where the Performance Analyzer can locate source files for editing. This choice is available from the Options menu on the Performance Analyzer - Window Manager window. When you select this choice, the Search Paths window appears. Related Information  Search Paths Window  Edit Source Choice  Performance Analyzer - Window Manager Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 11.3.3.1. Search Paths Window ═══ Use the Search Paths window to specify where the Performance Analyzer can locate source files for editing. When you are working in the WorkFrame environment, this window appears when you select the Search Paths... choice, which is available from the Options menu on the Performance Analyzer - Window Manager window. To locate a source file for editing, the Performance Analyzer must first locate the executable containing the name of the source file. The Performance Analyzer searches the following paths (in the order listed) to locate an executable: 1. Path specified in the Locate Executable window 2. Path specified in the Search path for executable files: entry field of the Search Paths window 3. Directory where the executable to be traced is located (if you selected the Edit source choice from the Trace Generation window) or the directory where the executable was located when the trace file was created (if you selected the Edit function choice from one of the diagrams) 4. The current working directory 5. Path specified by the PATH environment variable. To identify the name of the source file, the Performance Analyzer looks at the debug information in the executable. The Performance Analyzer then searches the following paths (in the order listed) to locate the source file: 1. Path specified in the Locate Source File window 2. Path specified in the Search path for source files: entry field of the Search Paths window 3. Path specified in the compile statement (if provided) 4. Directory where the executable to be traced is located (if you selected the Edit source choice from the Trace Generation window) or the directory where the executable was located when the trace file was created (if you selected the Edit function choice from one of the diagrams) 5. The current working directory 6. Path specified by the INCLUDE environment variable. To use the Search Paths window: 1. In the Search path for executable files: entry field, specify a path that you want the Performance Analyzer to use when looking for executable files. 2. In the Search path for source files: entry field, specify a path that you want the Performance Analyzer to use when looking for source files. 3. Select the appropriate push button to continue:  OK  Cancel  Help Note: The paths you enter are automatically saved for the current session. If you want to save the paths for subsequent sessions, select the Save choice. This choice is available from the Settings cascading choice, which is on the Options menu. Related Information  Edit Source Choice  Performance Analyzer - Window Manager Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 11.3.4. Unique Trace File Name Choice ═══ Select the Unique trace file name choice to have the Performance Analyzer give each trace file a unique name. This choice is available from the Options menu on the Performance Analyzer - Window Manager window. The default name for a trace file is myprog.trc, where myprog is the name of the program you are tracing. If you create more than one trace file from the same program, the Performance Analyzer uses the default naming convention and overwrites the previous trace file. However, if this choice is selected, the Performance Analyzer attaches a number to each file name. Select this choice to enable it. A check mark appears next to the choice to indicate that it is enabled. Select this choice again to disable it. Related Information  Introducing the Performance Analyzer  Selecting a Trace File to Analyze  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.3.5. Settings Cascading Choice ═══ Select the Settings cascading choice to display the following choices: Save Saves the current window settings. Restore initial defaults Restores the preset default settings. This choice is available from the Options menu on the Performance Analyzer - Window Manager window. Related Information  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.3.5.1. Save Choice ═══ Select the Save choice to save the current window settings for subsequent Performance Analyzer sessions. This choice is available from the Settings cascading choice, which is on the Options menu on the Trace Generation window. If you do not select this choice, settings remain active for the current session. If you select this choice, settings remain active for subsequent sessions because they are stored in the ICSPERF.INI file. The saved settings remain active until the ICSPERF.INI file is erased. The Performance Analyzer will save the following on the Performance Analyzer - Window Manager window:  Font settings  Paths specified in Search paths window  Quick exit setting  Show icons setting  Tree lines setting  Unique trace file name setting  Window position  Window size To restore the default settings, select the Restore initial defaults Related Information  Restore Initial Defaults Choice  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.3.5.2. Restore Initial Defaults Choice ═══ Select the Restore initial defaults choice to restore the Performance Analyzer default settings for the Performance Analyzer - Window Manager window. This choice is available from the Settings cascading choice, which is on the Options menu on the Performance Analyzer - Window Manager window. Related Information  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.4. Performance Analyzer - Window Manager Window Project Menu ═══ This menu appears on the Performance Analyzer - Window Manager window when you start the Performance Analyzer within the WorkFrame environment. The Project menu gives you direct access to all of the actions that you can perform from your current location. Related Information  Trace Generation Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 11.5. Performance Analyzer - Window Manager Window Help Menu ═══ Select choices from the Help menu to display the various types of Help information. The Help menu has the following choices: Help index Displays an index of Help topics. General help Displays Help for the active window. Using help Describes how to use Help. How do I? Displays task Help. Product information Displays information about the Performance Analyzer. Related Information  Introducing the Performance Analyzer  Selecting a Trace File to Analyze  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.5.1. Help Index Choice ═══ Select the Help index choice to display an alphabetical index of Performance Analyzer Help topics. This choice is available from the Help menu on the Performance Analyzer - Window Manager window. Use the Previous push button to return to the last panel you viewed. Use the Search... push button to locate topics in the index. Use the Print... push button to print a topic. Related Information  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.5.2. General Help Choice ═══ Select the General help choice to display Help information for the active window. This choice is available from the Help menu on the Performance Analyzer - Window Manager window. The online Help panel displayed is the same panel that is displayed when you place your cursor inside the window and press F1. Related Information  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.5.3. Using Help Choice ═══ Select the Using help choice for a description of how to use the Help facility. This choice is available from the Help menu on the Performance Analyzer - Window Manager window. Related Information  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.5.4. How Do I? Choice ═══ Select the How do I? choice to display the Performance Analyzer task help. This choice is available from the Help menu on the Performance Analyzer - Window Manager window. Related Information  Performance Analyzer - Window Manager Window  Keys Help. ═══ VisualAge C++ Help Menu Choices ═══ The central portion of the Help menu is dedicated to all the online documentation that is shipped with VisualAge C++. Making a selection from any of these cascaded menus launches the VisualAge C++ documentation associated with the menu item. You can find the same documentation in the Information folder found in the VisualAge C++ Desktop folder. The cascaded menus are organized as follows: At A Glance  Provides general information on using VisualAge C++, such as what is new in this release, the overall tutorial, a description of all the sample programs, and answers to frequently asked questions. Using VisualAge C++  Provides direct access to the individual sections of the User's Guide. For example, if you are using the Browser, you would look in the Browsing section for more information. How Do I... Selections  Provides access to the How Do I... information for each component of VisualAge C++. Use How Do I... information to find out how to perform common tasks within VisualAge C++. C/C++  Provides access to the information that is specific to programming in C and C++. Class Libraries  Provides access to the VisualAge C++ Open Class Library documentation. Visual Programming  Provides access to the information that is specific to creating your programs visually. OS/2, PM, and Graphics  Provides access to the documentation for the key aspects of OS/2, Presentation Manager, and graphics programming. IPF, REXX, and Editing  Provides access to the IPF, REXX and Editor references. SOM and WorkPlace Shell  Provides access to the information specific to SOM and the WorkPlace Shell. Multimedia  Provides access to the information that is specific to creating multimedia applications. ═══ 11.5.5. Product Information Choice ═══ Select the Product information choice to display copyright and version information about the Performance Analyzer application. This choice is available from the Help menu on the Performance Analyzer - Window Manager window. Related Information  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.6. Performance Analyzer - Window Manager Window Executable Pop-up Menu ═══ After you have created a trace file and selected a diagram in which to view it, the Performance Analyzer - Window Manager window displays a list of component file names, including your executable file, your trace file, and any open diagrams. If the Show icons choice is selected in the View menu, this icon, , is displayed next to each executable listed in the window. Click on the executable file name or icon to display the Executable pop-up menu. The choices listed in the pop-up menu are different if you click on another file type. The Performance Analyzer - Window Manager window Executable pop-up menu has the following choices: Create trace... Displays the window from which you can create a trace file. The file name on which you clicked appears in the window's Program Name entry field. Close Closes the selected executable, its associated trace file, and all diagrams in which the trace data is displayed. Related Information  Introducing Performance Analyzer  Selecting a Trace File to Analyze  Exiting the Performance Analyzer  Performance Analyzer - Window Manager Window. ═══ 11.6.1. Create Trace... Choice ═══ Select the Create trace... choice to start creating a trace file. This choice is available from the Executable pop-up menu on the Performance Analyzer - Window Manager window. When you select this choice, the Create Trace window appears. On the Create Trace window, specify the program you want to trace and any parameters you want to pass to the program. Note: Before creating a trace file, you must compile and link your program with the proper options. Related Information  Compiling and Linking Your Program  Create Trace Window  Creating a Customized Trace File  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.6.2. Close Choice ═══ Select the Close choice to close the selected executable, its trace file, and all diagrams in which the trace data is displayed. Only the Performance Analyzer - Window Manager window remains open. This choice is available from the Executable pop-up menu on the Performance Analyzer - Window Manager window. Related Information  Exiting the Performance Analyzer  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.7. Performance Analyzer - Window Manager Window Trace File Pop-up Menu ═══ After you have created a trace file and selected a diagram in which to view it, the Performance Analyzer - Window Manager window displays a list of component file names, including your executable file, your trace file, and any open diagrams. If the Show icons choice is selected in the View menu, this icon, , is displayed next to each trace file listed in the window. Click on the trace file name or icon to display the Trace File pop-up menu. The choices listed in the pop-up menu are different if you click on another file type. The Performance Analyzer - Window Manager window Trace File pop-up menu has the following choices: Analyze trace... Displays the window from which you can select Performance Analyzer diagrams to analyze the trace file. The file name on which you clicked appears in the window's Trace File Name entry field. Open as Call Nesting Opens the Call Nesting diagram and displays the trace file in it. Open as Dynamic Call Graph Opens the Dynamic Call Graph and displays the trace file in it. Open as Execution Density Opens the Execution Density diagram and displays the trace file in it. Open as Statistics Opens the Statistics diagram and displays the trace file in it. Open as Time Line Opens the Time Line diagram and displays the trace file in it. Close Closes the selected trace file and all diagrams in which the trace file is displayed. Delete File Deletes the selected trace file from your hard disk if you select Yes in the Trace File - Delete window (displayed when you select this choice). Related Information  Introducing the Performance Analyzer  Selecting a Trace File to Analyze  Performance Analyzer - Window Manager Window. ═══ 11.7.1. Analyze Trace... Choice ═══ Select the Analyze trace... choice to analyze an existing trace file. This choice is available from the Trace file pop-up menu on the Performance Analyzer - Window Manager window. When you select this choice, the Analyze Trace window appears. Related Information  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.7.2. Open As Call Nesting Choice ═══ Select the Open as Call Nesting choice to display the trace file in the Call Nesting diagram. This choice is available from the Trace file pop-up menu on the Performance Analyzer - Window Manager window. Related Information  Call Nesting Diagram  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.7.3. Open As Dynamic Call Graph Choice ═══ Select the Open as Dynamic Call Graph choice to display the trace file in the Dynamic Call Graph. This choice is available from the Trace file pop-up menu on the Performance Analyzer - Window Manager window. Related Information  Keys Help. ═══ 11.7.4. Open As Execution Density Choice ═══ Select the Open as Execution Density choice to display the trace file in the Execution Density diagram. This choice is available from the Trace file pop-up menu on the Performance Analyzer - Window Manager window. Related Information  Execution Density Diagram  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.7.5. Open As Statistics Choice ═══ Select the Open as Statistics choice to display the trace file in the Statistics diagram. This choice is available from the Trace file pop-up menu on the Performance Analyzer - Window Manager window. Related Information  Statistics Diagram  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.7.6. Open As Time Line Choice ═══ Select the Open as Time Line choice to display the trace file in the Time Line diagram. This choice is available from the Trace file pop-up menu on the Performance Analyzer - Window Manager window. Related Information  Time Line Diagram  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.7.7. Close Choice ═══ Select the Close choice to close the selected trace file and all diagrams in which the trace data is displayed. Only the Performance Analyzer - Window Manager window remains open. This choice is available from the Trace file pop-up menu on the Performance Analyzer - Window Manager window. Related Information  Exiting the Performance Analyzer  Performance Analyzer - Window Manager Window  Keys Help. ═══ 11.7.8. Delete File Choice ═══ When you select the Delete file choice, the trace file is deleted from the disk on which it is stored. This choice is available from the Trace file pop-up menu on the Performance Analyzer - Window Manager window. Related Information  Executable Pop-up Menu  Trace file Pop-up Menu  Performance Analyzer - Window Manager Window. ═══ 11.8. Performance Analyzer - Window Manager Window Diagram Pop-up Menu ═══ After you have created a trace file and selected a diagram in which to view it, the Performance Analyzer - Window Manager window displays a list of component file names, including your executable file, your trace file, and any open diagrams. If the Show icons choice is selected in the View menu, an icon is displayed next to each diagram file name listed in the window. Click on the diagram file name or icon to display the Diagram pop-up menu. The choices listed in the pop-up menu are different if you click on another file type. The Performance Analyzer - Window Manager window Diagram pop-up menu has the following choices: Display Makes the selected diagram active and brings it to the foreground of your desktop. Close Closes the selected diagram. Related Information  Introducing the Performance Analyzer  Show Icons Choice  Analyze Trace Window  Selecting a Trace File to Analyze  Performance Analyzer - Window Manager Window. ═══ 11.8.1. Display Choice ═══ When you select the Display choice, the Performance Analyzer makes the selected diagram active and brings it to the foreground of the desktop. This choice is available from the Diagram pop-up menu on the Performance Analyzer - Window Manager window. Related Information  Executable Pop-up Menu  Trace file Pop-up Menu  Performance Analyzer - Window Manager Window. ═══ 11.8.2. Close Choice ═══ Select the Close choice to close the selected diagram. Only the Performance Analyzer - Window Manager window remains open. This choice is available from the Diagram pop-up menu on the Performance Analyzer - Window Manager window. Related Information  Exiting the Performance Analyzer  Performance Analyzer - Window Manager Window  Keys Help. ═══ 12. Create Trace Window ═══ The Create Trace window lets you specify the name of the program that you want to trace and any parameters that you want to include in the trace. You can display the Create Trace window from the Performance Analyzer - Window Manager window by:  Clicking on the Create Trace... push button  Selecting the Create trace... choice from the File menu.  Clicking mouse button two on an executable file name or icon (if displayed), and then selecting Create trace... from the pop-up menu. Areas of the Create Trace Window  Program Name: Entry Field  Optional Entry Fields - Program Parameters: - Trace File Name: - Trace File Description:  Push Buttons - Find... - OK - Cancel - Help. Related Information  Creating a Trace File  Performance Analyzer - Window Manager Window  Trace Generation Window  Keys Help. ═══ 12.1. Program Name Entry Field ═══ Type the full path name and program you want to trace in the Program Name: entry field. This entry field is available on the Create Trace window. If the program is in your current directory, you do not have to type the path. Note: If you are not sure where the file is located, select the Find... push button. Related Information  Creating a Trace File  Performance Analyzer - Window Manager Window  Trace Generation Window  Keys Help. ═══ 12.2. Program Parameters Entry Field ═══ Type any parameters that you want to pass to your program in the Program Parameters: entry field. This entry field is available on the Create Trace window. Note: This entry field is optional. Related Information  Creating a Trace File  Performance Analyzer - Window Manager Window  Trace Generation Window  Keys Help. ═══ 12.3. Trace File Name Entry Field ═══ Type the name of the path and trace file in the Trace File Name: entry field. This entry field is available on the Create Trace window. The default name for the trace file is myprog.trc, where myprog is the name of the program you are tracing. The Performance Analyzer places the trace file in the current directory unless you specify a path. Note: This entry field is optional. Related Information  Creating a Trace File  Creating a Customized Trace File  Unique trace file name  Performance Analyzer - Window Manager Window  Trace Generation Window  Keys Help. ═══ 12.4. Trace File Description Entry Field ═══ Type any comments that you want to make about your trace in the Trace File Description: entry field. This entry field is available on the Create Trace window. A description can make a trace file easier to identify, especially when you create more than one trace file from the same program and use different options for each trace. The description is displayed in the Status Area of any open diagram. Note: This entry field is optional. Related Information  Creating a Trace File  Creating a Customized Trace File  Unique trace file name  Performance Analyzer - Window Manager Window  Trace Generation Window  Keys Help. ═══ 13. Analyze Trace Window ═══ The Analyze Trace window lets you specify the name of the trace file that you want to analyze and the Performance Analyzer diagrams in which you want to display it. Note: A trace file must have been created before you can open a diagram. See Creating a Trace File for instructions. You can display the Analyze Trace window from the Performance Analyzer - Window Manager window by:  Clicking on the Analyze Trace... push button  Selecting the Analyze trace... choice from the File menu.  Click mouse button two on a trace file name or icon (if displayed), and then selecting Analyze trace... from the pop-up menu. Areas of the Analyze Trace Window  Trace File Name: Entry Field  Diagrams Check Boxes - Call Nesting - Dynamic Call Graph - Execution Density - Statistics - Time Line  Push Buttons - Find... - OK - Cancel - Help. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Performance Analyzer - Window Manager Window  Keys Help. ═══ 13.1. Trace File Name Entry Field ═══ Type the full path and file name of the trace file that you want to analyze in the Trace File Name: entry field. This entry field is available on the Analyze Trace window. If the program is in your current directory, you do not have to type the path. Note: If you are not sure where the file is located, select the Find... push button. ═══ 14. Trace Generation Window ═══ The Trace Generation window lists the file names of the preloaded components in the program and lets you control which parts of your program are traced. A component can be an executable file, a dynamic load library (DLL) file, an object file, or a function. EXE and DLL files contain object files, and object files contain functions. Click on the plus and minus icons to expand and contract EXE, DLL, and object files to view or hide components. Note: Before creating a trace file, you must compile and link your program with the proper options. Areas of the Trace Generation Window  Menu Bar Summary - Application - Edit - View - Options - Project (only available when working in the WorkFrame environment) - Help  Pop-up Menus - Executable - Object File - Function  Push Button - Trace. Related Information  Compiling and Linking Your Program  Creating a Trace File  Creating a Customized Trace File  Keys Help. ═══ 14.1. Trace Generation Window Application Menu ═══ The Trace Generation window Application menu has the following choices: Window manager Makes the Performance Analyzer - Window Manager window active. Exit Performance Analyzer Lets you end the Performance Analyzer application. Related Information  Trace Generation Window  Keys Help. ═══ 14.1.1. Window Manager Choice ═══ Makes the Performance Analyzer - Window Manager window active and brings it to the foreground of your desktop. This choice is available from the Application menu on the Trace Generation window. Related Information  Trace Generation Window  Keys Help. ═══ 14.1.2. Exit the Performance Analyzer Choice ═══ Select the Exit the Performance Analyzer choice to end the Performance Analyzer application and close all associated windows. This choice is available from the Application menu on the Trace Generation window. Related Information  Exiting the Performance Analyzer  Trace Generation Window  Keys Help. ═══ 14.2. Trace Generation Window Edit Menu ═══ The Trace Generation window Edit menu has the following choices: Note: This is a dynamic menu that displays choices based on the type of component selected. Enable all executables Enables all functions in all executable files. Disable all executables Disables all functions in all executable files. Enable executable Enables all functions in a selected executable file. This choice is available when you select a disabled executable. Disable executable Disables all functions in a selected executable file. This choice is available when you select an enabled executable. Enable object file Enables all functions in a selected object file. This choice is available when you select a disabled object file. Disable object file Disables all functions in a selected object file. This choice is available when you select an enabled object file. Enable function Enables a function. This choice is available when you select a disabled function. Disable function Disables a function. This choice is available when you select an enabled function. Set trigger Sets a trigger on a function so that the Performance Analyzer traces the function and its associated calls. This choice is available when you select a function that does not have a trigger set on it. Note: If triggers are set, the Performance Analyzer traces all enabled components and only those functions on which triggers are set. If no triggers are set, the Performance Analyzer traces all enabled components. Remove trigger Removes a trigger on a function so that the Performance Analyzer does not trace the function and its associated calls. This choice is available when you select a function that has a trigger set on it. Note: If triggers are set, the Performance Analyzer traces all enabled components and only those functions on which triggers are set. If no triggers are set, the Performance Analyzer traces all enabled components. Related Information  Executable Pop-up Menu  Object File Pop-up Menu  Function Pop-up Menu  Trace Generation Window  Keys Help. ═══ 14.2.1. Enable All Executables Choice ═══ Select the Enable all executables choice to enable all functions in all executable files. This choice is available from the Edit menu on the Trace Generation window. When you enable executables, the Performance Analyzer includes information about them in the trace file. The default is to enable all components that have been compiled and linked with the proper options. To enable all executables, select Enable all executables from the Edit menu. Related Information  Disable All Executables Choice  Executable Pop-up Menu  Object file Pop-up Menu  Function Pop-up Menu  Trace Generation Window  Keys Help. ═══ 14.2.2. Disable All Executables Choice ═══ Select the Disable all executables choice to disable all functions in all executable files. This choice is available from the Edit menu on the Trace Generation window. When you disable executables, the Performance Analyzer does not include information about them in the trace file. The default is to enable all components that have been compiled and linked with the proper options. Related Information  Enable All Executables Choice  Executable Pop-up Menu  Object file Pop-up Menu  Function Pop-up Menu  Trace Generation Window  Keys Help. ═══ 14.2.3. Enable Executable Choice ═══ Select the Enable executable choice to enable all functions in a selected executable file. This choice is available from the Edit menu and the Executable pop-up menu on the Trace Generation window. You can select this choice when a disabled executable is selected. When you enable an executable, the Performance Analyzer includes information about the executable in the trace file. The default is to enable all components that have been compiled and linked with the proper options. Enable an executable in any of the following ways:  Click on the file name or icon of the executable you want to enable. Then select Enable executable from the Edit menu.  Double-click on the file name or icon of the executable you want to enable.  Click mouse button two on the file name or icon of the executable you want to enable. Then select Enable executable from the Executable pop-up menu. Note If the icon next to a component is:  Green (it also has no slash mark), the component is enabled.  Red (it also has a slash mark), the component is disabled.  White, the component cannot be traced. Related Information  Disable Executable Choice  Executable Pop-up Menu  Object file Pop-up Menu  Function Pop-up Menu  Trace Generation Window  Keys Help. ═══ 14.2.4. Disable Executable Choice ═══ Select the Disable executable choice to disable all functions in a selected executable file. This choice is available from the Edit menu and the Executable pop-up menu on the Trace Generation window. You can select this choice when an enabled executable is selected. When you disable an executable, the Performance Analyzer does not include information about the executable in the trace file. The default is to enable all components that have been compiled and linked with the proper options. Disable an executable in any of the following ways:  Click on the file name or icon of the executable you want to disable. Then select Disable executable from the Edit menu.  Double-click on the file name or icon of the executable you want to enable.  Click mouse button two on the file name or icon of the executable you want to disable. Then select Disable executable from the Executable pop-up menu. Note: If the icon next to a component is:  Green (it also has no slash mark), the component is enabled.  Red (it also has a slash mark), the component is disabled.  White, the component cannot be traced. Related Information  Enable Executable Choice  Executable Pop-up Menu  Object file Pop-up Menu  Function Pop-up Menu  Trace Generation Window  Keys Help. ═══ 14.2.5. Enable Object File Choice ═══ Select the Enable object file choice to enable all functions in a selected object file. This choice is available from the Edit menu and the Object file pop-up menu on the Trace Generation window. You can select this choice when a disabled object file is selected. When you enable an object file, the Performance Analyzer includes information about the object in the trace file. The default is to enable all components that have been compiled and linked with the proper options. Enable an object file in any of the following ways:  Click on the file name or icon of the object file you want to enable. Then select Enable object file from the Edit menu.  Double-click on the file name or icon of the object file you want to enable.  Click mouse button two on the file name or icon of the object file you want to enable. Then select Enable object file from the Object file pop-up menu. Note: If the icon next to a component is:  Green (it also has no slash mark), the component is enabled.  Red (it also has a slash mark), the component is disabled.  White, the component cannot be traced. Related Information  Disable Object File Choice  Executable Pop-up Menu  Object file Pop-up Menu  Function Pop-up Menu  Trace Generation Window  Keys Help. ═══ 14.2.6. Disable Object File Choice ═══ Select the Disable object file choice to disable all functions in a selected object file. This choice is available from the Edit menu and the Object file pop-up menu on the Trace Generation window. You can select this choice when an enabled object file is selected. When you disable an object file, the Performance Analyzer does not include information about the object in the trace file. The default is to enable all components that have been compiled and linked with the proper options. Disable an object file in any of the following ways:  Click on the file name or icon of the object file you want to disable. Then select Disable object file from the Edit menu.  Double-click on the file name or icon of the object file you want to disable.  Click mouse button two on the file name or icon of the object file you want to disable. Then select Disable object file from the Object file pop-up menu. Note: If the icon next to a component is:  Green (it also has no slash mark), the component is enabled.  Red (it also has a slash mark), the component is disabled.  White, the component cannot be traced. Related Information  Enable Object File Choice  Executable Pop-up Menu  Object file Pop-up Menu  Function Pop-up Menu  Trace Generation Window  Keys Help. ═══ 14.2.7. Enable Function Choice ═══ Select the Enable function choice to enable a function. This choice is available from the Edit menu and the Function pop-up menu on the Trace Generation window. You can select this choice when a disabled function is selected. When you enable a function, the Performance Analyzer includes information about the function in the trace file. The default is to enable all components that have been compiled and linked with the proper options. Enable a function in any of the following ways:  Click on the name or icon of the function you want to enable. Then select Enable function from the Edit menu.  Double-click on the name or icon of the function you want to enable.  Click mouse button two on the file name or icon of the function you want to enable. Then select Enable function from the Function pop-up menu. Note: If the icon next to a component is:  Green (it also has no slash mark), the component is enabled.  Red (it also has a slash mark), the component is disabled.  White, the component cannot be traced. Related Information  Disable Function Choice  Executable Pop-up Menu  Object file Pop-up Menu  Function Pop-up Menu  Trace Generation Window  Keys Help. ═══ 14.2.8. Disable Function Choice ═══ Select the Disable function choice to disable a function. This choice is available from the Edit menu and the Function pop-up menu on the Trace Generation window. You can select this choice when an enabled function is selected. When you disable a function, the Performance Analyzer does not include information about the function in the trace file. The default is to enable all components that have been compiled and linked with the proper options. Disable a function in any of the following ways:  Click on the name or icon of the function you want to disable. Then select Disable function from the Edit menu.  Double-click on the name or icon of the function you want to disable.  Click mouse button two on the file name or icon of the function you want to disable. Then select Disable function from the Function pop-up menu. Note: If the icon next to a component is:  Green (it also has no slash mark), the component is enabled.  Red (it also has a slash mark), the component is disabled.  White, the component cannot be traced. Related Information  Enable Function Choice  Executable Pop-up Menu  Object file Pop-up Menu  Function Pop-up Menu  Trace Generation Window  Keys Help. ═══ 14.2.9. Set Trigger Choice ═══ Select the Set trigger choice to set a trigger on a function. This choice is available from the Edit menu and the Function pop-up menu on the Trace Generation window. You can select this choice when a function is selected. You select a function by clicking on the file name or icon of the function in the Trace Generation window. A trigger turns tracing on when it is called and then turns tracing off when it returns. By setting triggers to start or stop tracing at selected points in your program, you can control the size of your trace file. For more information on controlling the size of your trace file, see Creating a Customized Trace File. The Performance Analyzer allows you to set multiple triggers. If a trigger function is nested within another trigger function, tracing is turned off only after the outer function returns. Notes  When a trigger is set on a function inside an object file, only that function and its children log events in the object file. To receive trace data about other functions in the object file, you can set triggers on multiple functions.  If triggers are set, the Performance Analyzer traces all enabled components and only those functions on which triggers are set. If no triggers are set, the Performance Analyzer traces all enabled components. Set a trigger in either of the following ways: 1. Method One a. On the Trace Generation window, select the function you want to trigger. b. Select the Set trigger choice from the Edit menu. The letter T appears in the icon next to the function name. 2. Method Two a. On the Trace Generation window, click mouse button two on the function you want to trigger or the icon next to it. b. Click on the Set trigger choice in the Function pop-up menu. Related Information  Setting and Removing Triggers  Remove Trigger Choice  Function Pop-up Menu  Trace Generation Window  Keys Help. ═══ 14.2.10. Remove Trigger Choice ═══ Select the Remove trigger choice to remove a trigger that has been set on a function. This choice is available from the Edit menu and the Function pop-up menu on the Trace Generation window. You can select this choice when a function on which a trigger has been set is selected. You select a function by clicking on the function name or icon in the Trace Generation window. A trigger turns tracing on when it is called and then turns tracing off when it returns. By setting triggers to start or stop tracing at selected points in your program, you can control the size of your trace file. For more information on controlling the size of your trace file, see Creating a Customized Trace File. The Performance Analyzer allows you to set multiple triggers. If a trigger function is nested within another trigger function, tracing is turned off only after the outer function returns. Note: If triggers are set, the Performance Analyzer traces all enabled components and only those functions on which triggers are set. If no triggers are set, the Performance Analyzer traces all enabled components. Remove a trigger in either of the following ways: 1. Method One a. Select a function on which a trigger has been set. A function that has a trigger has the letter T in the icon next to its function name in the Trace Generation window. b. Select the Remove trigger choice from the Edit menu. The T is removed from the icon next to the function name. 2. Method Two a. Select a function on which a trigger has been set by clicking mouse button two on the function name or the icon next to it in the Trace Generation window. b. Click on the Remove trigger choice in the Function pop-up menu. Related Information  Setting and Removing Triggers  Set Trigger Choice  Function Pop-up Menu  Trace Generation Window  Keys Help. ═══ 14.3. Trace Generation Window View Menu ═══ The Trace Generation window View menu has the following choices: Traceable filter Displays only the components that are traceable. Tree lines Displays lines between file names to show relationships. Related Information  Trace Generation Window  Keys Help. ═══ 14.3.1. Traceable Filter Choice ═══ Select the Traceable filter choice to view only the components that are traceable. This choice is available from the View menu on the Trace Generation window. To filter the traceable components, select Traceable filter from the View menu. A check mark is displayed next to the choice to show it is enabled. To reset the filter, select Traceable filter from the View menu. The check mark is removed to show the choice is disabled. Note: The settings you enter are saved for the current session. If you want to save the settings for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Trace Generation Window  Keys Help. ═══ 14.3.2. Tree Lines Choice ═══ Select the Tree lines choice to display directory tree lines. This choice is available from the View menu on the Trace Generation window. A check mark next to this choice indicates that it is selected. To remove tree lines, select the choice again. The check mark is removed to show the choice is disabled. Note: The settings you enter are saved for the current session. If you want to save the settings for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Trace Generation Window  Keys Help. ═══ 14.4. Trace Generation Window Options Menu ═══ Select choices from the Options menu to customize your trace sessions. The Trace Generation window Options menu has the following choices: Buffer control... Select the size of the event log buffer, and enable and disable buffer wrapping. Call depth... Select the call depth limit for each thread. File access Select to trace or not trace file accesses. Font... Displays the Font window, which lets you change the font, font style, and font size for the Trace Generation window. Name trace file... Type a new path or rename the trace file for the program you are analyzing and change the trace file description. Timeout control... Select the maximum number of seconds your program may run without logging events. Use this choice when your program is in a continuous loop or deadlock. Time stamp events Select to log or not log time stamps. Settings Displays a cascaded menu that lets you save settings or restore initial default settings. Related Information  Trace Generation Window  Keys Help. ═══ 14.4.1. Buffer Control... Choice ═══ Select the Buffer control... choice to set the size of the event log buffer, and to enable or disable buffer wrapping. This choice is available from the Options menu on the Trace Generation window. 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 buffer wrapping to choose when the data is written to the trace file. The default is to disable buffer wrapping. When you select Buffer control..., a Buffer Control window appears. Related Information  Creating a Customized Trace File  Trace Generation Window  Keys Help. ═══ 14.4.1.1. Buffer Control Window ═══ Use the Buffer Control window to set the size of the event log buffer and choose to enable or disable buffer wrapping. This window appears when you select the Buffer control... choice, which is available from the Options menu on the Trace Generation window. The Buffer control window is displayed when you select the Buffer control... choice from the Options menu on the Trace Generation window. The number of times the buffer is written to the trace file (buffer flushes) is listed in the Statistics diagram. The buffer is flushed when it is full and whenever a dynamic link library (DLL) is loaded. 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 buffer wrapping to choose when the data is written to the trace file. The default for buffer wrapping is disable. This window has two group headings: Buffer Size and Buffer Wrapping. Buffer Size Group Heading The Buffer Size determines the size of the event log buffer. 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). Set the buffer size by selecting the spin buttons in the Buffer Size group heading. The top spin button increases the buffer size and the bottom spin button decreases the buffer size. Select the appropriate push button to continue:  OK  Cancel  Help. Note: The settings you enter are saved for the current session. If you want to save the settings for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Buffer Wrapping Group Heading You can enable or disable buffer wrapping to choose when the data is written to the trace file. When buffer wrapping is enabled, the trace data is written to the trace file only when tracing has stopped. As the program is traced, the buffer fills and overwrites older events in the buffer with newer ones. Since the buffer is flushed only when the program ends, less disk space is needed for the trace file, but some trace data is lost. When buffer wrapping is disabled, the data is written to the trace file every time the buffer fills. The default for buffer wrapping is disable. Enable or disable buffer wrapping by selecting a radio button.  Select the On radio button to enable buffer wrapping.  Select the Off radio button to disable buffer wrapping. Select the appropriate push button to continue:  OK  Cancel  Help. Note: The settings you enter are saved for the current session. If you want to save the settings for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Creating a Customized Trace File  Trace Generation Window  Keys Help. ═══ 14.4.2. Call Depth... Choice ═══ Select the Call depth... choice to set the nesting depth for each thread in your program. This choice is available from the Options menu on the Trace Generation window. You can select as many as 64 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 Call depth, a Call Depth window appears. Related Information  Creating a Customized Trace File  Trace Generation Window  Keys Help. ═══ 14.4.2.1. Call Depth Window ═══ Use the Call Depth window to set the nesting depth for each thread in your program. This window appears when you select the Call depth... choice, which is available from the Options menu on the Trace Generation window. You can select as many as 64 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. Changing the Call Depth The Call Depth window displays 64 thread entry fields. To set call depth, use any of the following methods: 1. Method One a. Select (or deselect) threads by clicking on them. b. Click on the spin buttons next to the Set selected entry field until the desired call depth is shown, or click in the entry field and type the desired call depth. c. Press the Set selected push button to change all selected threads to the desired call depth. Note: To disable tracing of any event in a thread, set the call depth of that thread to 0. d. Select the appropriate push button to continue:  OK  Cancel  Help. 2. Method Two a. Select a thread by double-clicking on it. A box appears around the value in the Depth column of the selected thread. b. Type the desired call depth. c. Press Enter. d. Repeat these steps for each thread you want to change. Note: The settings you enter are saved for the current session. If you want to save the settings for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Creating a Customized Trace File  Trace Generation Window  Keys Help. ═══ 14.4.3. File Access Choice ═══ Select the File access choice to keep track of file access calls using the following DOS calls:  DosOpen()  DosRead()  DosWrite()  DosClose()  DosDupHandle()  DosResetBuffer()  DosSetFilePtr()  DosSetFileLocks()  DosSetFileSize()  DosQueryFileInfo()  DosQueryHType() This choice is available from the Options menu on the Trace Generation window. You can only select this choice if you have linked _DOSCALL.LIB into your program. When a DOS call references a file, the Performance Analyzer keeps track of the file name associated with the traced DOS calls. These calls are shown in the diagrams under the functions that made the file accesses. They appear as function names with their corresponding files in parentheses. To set file access:  Select the Trace Generation window Options menu.  Select the File access choice. A check mark is displayed next to the choice to show that it is selected. To reset file access:  Select the Trace Generation window Options menu.  Select the File access choice. The check mark is removed to show that the choice is not selected. Notes:  The settings you enter are saved for the current session. If you want to save the settings for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu.  You can only select the File access choice when the _DOSCALL.LIB file is linked with your program. Related Information  Creating a Customized Trace File  Trace Generation Window  Keys Help. ═══ 14.4.4. Font... Choice ═══ Select the Font... choice to change the font, font style, and font size for the text area on the Trace Generation window. This choice is available from the Options menu on the Trace Generation window. When you select this choice, the Font window appears. The Font window has the following areas: Name entry field Type a font name in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a name from the list. Size entry field Type a font size in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a size from the list. Style entry field Type a font style in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a style from the list. Emphasis check boxes Click on one of these check boxes to outline, underscore, or strikeout text. Sample box This box shows a sample of how text will appear with the settings you have selected. Ok push button Changes the font according to the settings you selected. Reset push button Changes all font settings to the default settings. Cancel push button Closes the window without making changes. Note: The settings you enter are saved for the current session. If you want to save the settings for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Trace Generation Window  Keys Help. ═══ 14.4.5. Name Trace File... Choice ═══ Select the Name trace file choice to create a trace file with a name other than the default or to rename a trace file you are analyzing. This choice is available from the Options menu on the Trace Generation window. The default name for the trace file is myprog.trc, where myprog is the name of the program you are tracing. When you select Name trace file..., a Name Trace File window appears. On this window, you can also add or change a trace file description. Related Information  Creating a Customized Trace File  Trace Generation Window  Keys Help. ═══ 14.4.5.1. Name Trace File Window ═══ Use the Name Trace File window to give a trace file a different name and to attach a description to it. This window appears when you select the Name trace file... choice from the Options menu on the Trace Generation window. The default name for a trace file is myprog.trc, where myprog is the name of the program you are tracing. If you create more than one trace file from the same program, The Performance Analyzer uses the default naming convention and overwrites the previous trace file. This choice is useful when you want to save two or more trace files created from the same program. If you try to create a trace file with the same name as one that is currently displayed in a diagram, the Performance Analyzer allows you to display this window and name the new trace file. For more information, see Resolve Name Conflict Window. A description can make a trace file easier to identify, especially when you create more than one trace file from the same program and use different options for each trace. The description is displayed in the Status Area of any open diagram. Naming the Trace File and Adding a Description To name or change the name of a trace file and attach a description to it: 1. Type the new path, file name, and file extension in the Trace file entry field. 2. Type a description for the trace file in the Description entry field. Note: This entry field is optional. 3. Select the appropriate push button to continue:  OK  Cancel  Help. Related Information  Resolve Name Conflict Window  Unique Trace File Name Choice  Trace Generation Window  Keys Help. ═══ 14.4.6. Timeout Control... Choice ═══ Select the Timeout control... choice to specify the maximum number of seconds your program can run without logging events. This choice is available from the Options menu on the Trace Generation window. Use this choice when your program deadlocks to determine where the problem is located. When you select Timeout control..., a Timeout Control window appears. Related Information  Creating a Customized Trace File  Trace Generation Window  Keys Help. ═══ 14.4.6.1. Timeout Control Window ═══ Use the Timeout Control window to specify the maximum number of seconds your program can run without logging events. This window appears when you select the Timeout control... choice, which is available from the Options menu on the Trace Generation window. Use this choice when your program deadlocks to determine where the problem is located. Setting a Timeout To use the Timeout Control 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 that there is not a maximum limit. 2. Select the appropriate push button to continue:  OK  Cancel  Help. Note: The settings you enter are saved for the current session. If you want to save the settings for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Analyze Trace Window  Trace Generation Window  Keys Help. ═══ 14.4.7. Time Stamp Events Choice ═══ Select the Time stamp events choice to enable or disable time stamps. This choice is available from the Options menu on the Trace Generation window. To set time stamp events on:  Select the Trace Generation window Options menu.  Select the Time stamp events choice. A check mark is displayed next to the choice to show that it is selected. To set time stamp events off:  Select the Trace Generation window Options menu.  Select the Time stamp events choice. The check mark is removed to show that the choice is not selected. If you choose to disable time stamps, the Performance Analyzer produces a smaller trace file and only the Statistics and Call Nesting diagrams and the Dynamic Call Graph can be viewed. The default is to have time stamps enabled. Note: The settings you enter are saved for the current session. If you want to save the settings for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Creating a Customized Trace File  Trace Generation Window  Keys Help. ═══ 14.4.8. Settings Cascading Choice ═══ Select the Settings cascading choice to display a cascaded menu that lets you save settings or restore Analyzer default settings. This choice is available from the Options menu on the Trace Generation window. Related Information  Trace Generation Window  Keys Help. ═══ 14.4.8.1. Save Choice ═══ Select the Save choice to save the current window settings for subsequent Performance Analyzer sessions. This choice is available from the Settings cascading choice, which is on the Options menu on the Trace Generation window. If you do not select this choice, settings remain active for the current session. If you select this choice, settings remain active for subsequent sessions because they are stored in the ICSPERF.INI file. The saved settings remain active until the ICSPERF.INI file is erased. The Performance Analyzer will save the following settings on the Trace Generation window:  Buffer size  Buffer wrapping  File access  Font  Call depth  Time stamp events  Timeout Control  Traceable filter  Tree lines  Window position  Window size To restore the default settings, select the Restore Initial Defaults Related Information  Restore Initial Defaults Choice  Trace Generation Window  Keys Help. ═══ 14.4.8.2. Restore Initial Defaults Choice ═══ Select the Restore Initial Defaults choice to restore the Performance Analyzer default settings for the Trace Generation window. This choice is available from the Settings cascading choice, which is on the Options menu on the Trace Generation window. Related Information  Trace Generation Window  Keys Help. ═══ 14.5. Trace Generation Window Project Menu ═══ This menu appears on the Trace Generation window when you start the Performance Analyzer within the WorkFrame environment. The Project menu gives you direct access to all of the actions that you can perform from your current location. When you select the Edit source choice from this menu, the source file for a selected object file or function is displayed in WorkFrame's default editor. Related Information  Edit Source Choice  Search Paths Window  Trace Generation Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 14.5.1. Edit Source Choice ═══ Select the Edit source choice to edit a source file in WorkFrame's default editor. This choice lets you edit the source for an object file or a function selected on the Trace Generation window. When you are working in the WorkFrame environment, this choice is available from the Project menu on the Trace Generation window. It is also available from the Object file pop-up menu and the Function pop-up menu on the Trace Generation window. To locate a source file for editing, the Performance Analyzer must first locate the executable containing the name of the source file. The Performance Analyzer searches the following paths (in the order listed) to locate an executable: 1. Path specified in the Locate Executable window 2. Path specified in the Search path for executable files: entry field of the Search Paths window 3. Directory where the executable to be traced is located 4. The current working directory 5. Path specified by the PATH environment variable. To identify the name of the source file, the Performance Analyzer looks at the debug information in the executable. The Performance Analyzer then searches the following paths (in the order listed) to locate the source file: 1. Path specified in the Locate Source File window 2. Path specified in the Search path for source files: entry field of the Search Paths window 3. Path specified in the compile statement (if provided) 4. Directory where the executable to be traced is located 5. The current working directory 6. Path specified by the INCLUDE environment variable. If, after searching these paths, the Performance Analyzer cannot find the: 1. Executable, it displays the Locate Executable window to let you enter the path where the executable resides. 2. Source file, it displays the Locate Source File window to let you enter the path where the source file resides. If you are editing the source for:  An object file, the source is opened to the first line of the file.  A function, the source is opened to the first line of the function's code. Notes 1. The Performance Analyzer remembers the paths you enter in the Locate Executable and Locate Source File windows and uses them to look for files the next time you select the Edit source choice. 2. You can specify paths that you want the Performance Analyzer to use by selecting the Search Paths choice in the Options menu on the Performance Analyzer - Window Manager window. The paths you enter are automatically saved for the current session. If you want to save the paths for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Locate Executable Window  Locate Source File Window  Search Paths Window  Trace Generation Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 14.6. Trace Generation Window Help Menu ═══ Select choices from the Help menu to display the various types of Help information. The Help menu has the following choices: Help index Displays an index of Help topics. General help Displays Help for the active window. Using help Describes how to use Help. How do I? Displays task Help. Product information Displays information about the Performance Analyzer. Related Information  Trace Generation Window  Keys Help. ═══ 14.6.1. Help Index Choice ═══ Select the Help index choice to display an alphabetical index of Performance Analyzer Help topics. This choice is available from the Help menu on the Trace Generation window. Use the Previous push button to return to the last topic you viewed. Use the Search... push button to locate topics in the index. Use the Print... push button to print a topic. Related Information  Trace Generation Window  Keys Help. ═══ 14.6.2. General Help Choice ═══ Select the General help choice to display Help information for the active window. This choice is available from the Help menu on the Trace Generation window. The online Help panel displayed is the same panel that is displayed when you place your cursor inside the window and press F1. Related Information  Trace Generation Window  Keys Help. ═══ 14.6.3. Using Help Choice ═══ Select the Using help choice for a description of how to use the Help facility. This choice is available from the Help menu on the Trace Generation window. Related Information  Trace Generation Window  Keys Help. ═══ 14.6.4. How Do I? Choice ═══ Select the How do I? choice to display the Performance Analyzer task help. This choice is available from the Help menu on the Trace Generation window. Related Information  Trace Generation Window  Keys Help. ═══ 14.6.5. Product Information Choice ═══ Select the Product information choice to display copyright and version information about the Performance Analyzer application. This choice is available from the Help menu on the Trace Generation window. Related Information  Trace Generation Window  Keys Help. ═══ 14.7. Trace Generation Window Executable Pop-up Menu ═══ The Trace Generation window displays a list of component file names that make up your program. Click mouse button two on the file name or icon of an executable (EXE) or dynamic link library (DLL) file to display the Executable pop-up menu. The pop-up menu and the choices listed in the menu are different if you click on another file type. The Trace Generation window Executable pop-up menu has the following choices: Disable executable Disables the selected executable file so that the Performance Analyzer does not record trace analysis data for it in the trace file. This choice is available when you select an enabled executable. Enable executable Enables the selected executable file so that the Performance Analyzer records trace analysis data for it in the trace file. This choice is available when you select a disabled executable. Related Information  Introducing the Performance Analyzer  Edit Menu  Trace Generation Window  Keys Help. ═══ 14.8. Trace Generation Window Object File Pop-up Menu ═══ The Trace Generation window displays a list of component file names that make up your program, including those of object files. Click mouse button two on the file name of an object file (or the plus/minus icon next to it) to display the Object File pop-up menu. The pop-up menu and the choices listed in the menu are different if you click on another file type. The Trace Generation window Object File pop-up menu has the following choices: Disable object file Disables the selected object file so that the Performance Analyzer does not record trace analysis data for it in the trace file. This choice is available when you select an enabled object file. Enable object file Enables the selected object file so that the Performance Analyzer records trace analysis data for it in the trace file. This choice is available when you select a disabled object file. Edit source Displays the source file for a selected object file in WorkFrame's default editor. The Performance Analyzer finds the source file and opens it to the first line of the file. Related Information  Edit Menu  Edit Source Choice  Project Menu  Trace Generation Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 14.9. Trace Generation Window Function Pop-up Menu ═══ The Trace Generation window displays a list of component file names that make up your program, including those of functions. Click mouse button two on the name of a function (or the plus/minus icon next to it) to display the Function pop-up menu. The pop-up menu and the choices listed in the menu are different if you click on another file type. The Trace Generation window Function pop-up menu has the following choices: Disable function Disables the selected function so that the Performance Analyzer does not record trace analysis data for it in the trace file. This choice is available when you select an enabled function. Enable function Enables the selected function so that the Performance Analyzer records trace analysis data for it in the trace file. This choice is available when you select a disabled function. Set trigger Sets a trigger on a function so that the Performance Analyzer traces the function and its associated calls. This choice is available when you select a function that does not have a trigger set on it. Note: If triggers have not been set, the Performance Analyzer traces enabled executables, DLLs, object files, and functions (and their associated calls). If triggers have been set, the Performance Analyzer traces enabled executables, DLLs, and object files, but it only traces functions (and their associated calls) on which triggers have been set. Remove trigger Removes a trigger on a function so that the Performance Analyzer does not trace the function and its associated calls. This choice is available when you select a function that has a trigger set on it. Note: If triggers have not been set, the Performance Analyzer traces enabled executables, DLLs, object files, and functions (and their associated calls). If triggers have been set, the Performance Analyzer traces enabled executables, DLLs, and object files, but it only traces functions (and their associated calls) on which triggers have been set. Edit source Displays the source file for a selected function in WorkFrame's default editor. The Performance Analyzer finds the source file and opens it to the line where the function begins. Related Information  Edit Menu  Edit Source Choice  Project Menu  Trace Generation Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 14.10. Locate Executable Window ═══ When you select the Edit source choice (available when working in the WorkFrame environment), the Performance Analyzer must find the source file containing the code you want to edit before it can be displayed in the editor. When searching for a source file, the Performance Analyzer first looks for the executable containing the object file or function you want to edit. (You can select object files and functions for editing on the Trace Generation window. You can select functions for editing on any of the diagrams.) Then it looks at the debug information in the executable to identify the name of the source file containing the code you want to edit. The Performance Analyzer searches the following paths (in the order listed) when looking for an executable file: 1. Path specified in the Locate Executable window 2. Path specified in the Search path for executable files: entry field of the Search Paths window 3. Directory where the executable to be traced is located (if you selected the Edit source choice from the Trace Generation window) or the directory where the executable was located when the trace file was created (if you selected the Edit function choice from one of the diagrams) 4. The current working directory 5. Path specified by the PATH environment variable. The Locate Executable window is only displayed if the Performance Analyzer cannot find the executable in any of these paths. To use the Locate Executable window: 1. Enter the path name where the executable containing the source file is located. Note: If you are not sure where the file is located, select the Find... push button. 2. Select the appropriate push button to continue:  OK  Cancel  Help Notes 1. The Performance Analyzer remembers the path you enter in the Locate Executable window and uses it to look for files the next time you select the Edit source choice. 2. Specify paths that you want the Performance Analyzer to use by selecting the Search Paths choice in the Options menu on the Performance Analyzer - Window Manager window. The paths you enter are automatically saved for the current session. If you want to save the paths for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Edit Source Choice  Locate Source File Window  Search Paths Window  Trace Generation Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 14.11. Locate Source File Window ═══ When you select the Edit source choice (available when working in the WorkFrame environment), the Performance Analyzer must find the source file containing the code you want to edit before it can be displayed in the editor. When searching for a source file, the Performance Analyzer first looks for the executable containing the object file or function you want to edit. Then it looks at the debug information in the executable to identify the name of the source file containing the code you want to edit. The Performance Analyzer searches the following paths (in the order listed) when looking for a source file: 1. Path specified in the Locate Source File window 2. Path specified in the Search path for source files: entry field of the Search Paths window 3. Path specified in the compile statement (if provided) 4. Directory where the executable to be traced is located (if you selected the Edit source choice from the Trace Generation window) or the directory where the executable was located when the trace file was created (if you selected the Edit function choice from one of the diagrams) 5. The current working directory 6. Path specified by the INCLUDE environment variable. The Locate Source File window is only displayed if the Performance Analyzer cannot find the source file in any of these paths. To use the Locate Source File window: 1. Enter the path name where the source file is located. Note: If you are not sure where the file is located, select the Find... push button. 2. Select the appropriate push button to continue:  OK  Cancel  Help Notes 1. The Performance Analyzer remembers the path you enter in the Locate Source File window and uses it to look for files the next time you select the Edit source choice. 2. Specify paths that you want the Performance Analyzer to use by selecting the Search Paths choice in the Options menu on the Performance Analyzer - Window Manager window. The paths you enter are automatically saved for the current session. If you want to save the paths for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Edit Source Choice  Locate Executable Window  Search Paths Window  Trace Generation Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 14.12. Resolve Name Conflict Window ═══ The Resolve Name Conflict window appears when you're trying to create a new trace file with the same name as one that is currently displayed in a diagram. To correct this problem, you can do any of the following:  Give the trace file a different name. To do this: 1. Click on the Rename trace file push button. 2. Enter a different trace file name in the Name Trace File window. You can also give the trace file a description that will make it easier to identify. 3. Click on the OK push button.  Overwrite the existing trace file by creating a new one. To do this: 1. Click on the Cancel push button to return to the Window Manager window. 2. Close the diagram or diagrams using the trace file you want to recreate. 3. Create another trace file using the same executable file.  Create another trace file using the same executable file, but with Unique trace file name choice selected. To do this: 1. Click on the Cancel push button to return to the Window Manager window. 2. Select Unique trace file name from the Options menu on the Performance Analyzer - Window Manager window. 3. Create another trace file using the same executable file. ═══ 15. Application Monitor Window ═══ After you select the Trace push button (on the Trace Generation window) to start tracing your program, the Performance Analyzer displays the Application Monitor window. This window is displayed until your entire program has run or you select the Stop push button, which causes your program to stop running. When you stop the program, you also stop the collection of trace data. Areas of the Application Monitor Window  Status Area  Push Buttons - Stop - Trace on - Trace off. Note: The Help push button displays this Help information. Related Information  Selecting a Trace File to Analyze  Trace Generation Window  Keys Help. ═══ 15.1. Status Area ═══ The following information is displayed in the Status Area on the Application Monitor window:  Name of the program being traced  Name of the trace file  Number of bytes written to the trace file  Number of events written to the trace file Related Information  Trace Off Push Button  Trace On Push Button  Selecting a Trace File to Analyze  Trace Generation Window  Keys Help. ═══ 16. Call Nesting Diagram ═══ Call Nesting Diagram The Call Nesting diagram shows the trace file as a vertical series of function calls and returns. Use this diagram to diagnose problems with critical sections, sequencing protocols, program deadlocks and crashes, and thread delays. Each thread in the Call Nesting diagram has its own starting column of functions. A call is shown as a step to the right and a return is shown as a line back to the left. The calls are labeled with the name of the function being called. Use the mouse to select a call, a return or a user event. When the call is selected, it is highlighted. Context switches between threads are shown by dashed horizontal lines. While the vertical lines do not show elapsed scaled times in this diagram, you can clearly see the flow of control and the interactions among the various threads. You can use this diagram to find where a deadlock occurred. Areas of the Call Nesting Window The following topics describe the areas of the Call Nesting diagram:  Menu Bar Summary The choices available from the Call Nesting diagram menu bar are: - Trace file - Edit - View - Options - Project - Help  Status Area The Status Area provides information about the following: - Trace Description - Filters  Call Nesting Pop-up Menus - Call Nesting Diagram Pop-up - Call Nesting Selected Item Pop-up Related Information  Analyze Trace Window  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 16.1. Call Nesting Trace File Menu ═══ The following choices are available from the Call Nesting Trace file menu: Open as Shows a new or an additional diagram. Printer settings... Allows you to choose printer settings for your output. Print selected region... Prints a selected area of the diagram. Window Manager Displays the Window Manager Exit Performance Analyzer Exits the Performance Analyzer. Related Information  Analyze Trace Window  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Keys Help. ═══ 16.1.1. Open as Cascading Choice ═══ Select the Open as 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 as from the Trace file menu. A cascaded menu is displayed with the following choices: Call Nesting Dynamic Call Graph Execution Density Statistics Time Line 2. Select the name of the diagram you want to view. A new window opens to display the diagram you selected. Related Information  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Keys Help. ═══ 16.1.1.1. Call Nesting Choice ═══ The Call Nesting choice is available from the Open as cascaded menu. When you select Call Nesting diagram, the Call Nesting Diagram displays. Related Information  Open As Choice  Keys Help. ═══ 16.1.1.2. Dynamic Call Graph Choice ═══ The Dynamic Call Graph choice is available from the Open as cascaded menu. When you select Dynamic Call Graph, the Dynamic Call Graph displays. Related Information  Open As Choice  Keys Help. ═══ 16.1.1.3. Execution Density Choice ═══ The Execution Density choice is available from the Open as cascaded menu. When you select Execution Density, the Execution Density Diagram displays. Related Information  Open As Choice  Keys Help. ═══ 16.1.1.4. Statistics Choice ═══ The Statistics choice is available from the Open as cascaded menu. When you select Statistics, the Statistics Diagram displays. Related Information  Open As Choice  Keys Help. ═══ 16.1.1.5. Time Line Choice ═══ The Time Line choice is available from the Open as cascaded menu. When you select Time Line, the Time Line Diagram displays. Related Information  Open As Choice  Keys Help. ═══ 16.1.2. Printer Settings... Choice ═══ Select the Printer settings... choice to select settings for your print jobs. When you select the Printer settings... choice, the Printer Settings window appears.  OK  Font  Job  Cancel  Help Related Information  Keys Help. ═══ Printer Settings Window ═══ The Printer Settings window allows you to choose which printer you want to use and how your output will be printed. This window displays a list of all printers installed on your system. You can select your choice by highlighting it. Select the Font push button to change the font of the print job. Note: The Execution Density diagram does not have a Font push button. From the Font window, select the appropriate choices. Select the Job properties... push button for more detailed information about your print job. From the Job properties... window, select the appropriate push buttons and check boxes. You can select from the following:  Orientation  Form Configuration  Select Form Source  Select Form  Default Font  Resolution  Performance Options From the Printer Settings window, select the appropriate push button. Related Information  Keys Help. ═══ 16.1.3. Print Selected Region... Choice ═══ Select the Print selected region... choice to print a selected area of the Call Nesting diagram. To print an area of the Call Nesting diagram, highlight the area and then select this choice from the Trace file menu. The Print Selected Region window appears. Related Information  Keys Help. ═══ Print Selected Region Window ═══ The Print Selected Region window displays your printer and job name. Select the appropriate push button to continue. Click on the Print push button to accept the defaults. The diagram will print on the selected printer. Click on the Cancel push button to cancel the print request. Related Information  Keys Help. ═══ 16.1.4. Window Manager Choice ═══ Select the Window manager choice to display the Window Manager window. Related Information  Performance Analyzer - Window Manager  Keys Help. ═══ 16.1.5. Exit Performance Analyzer Choice ═══ Select the Exit Performance Analyzer choice from the Trace file menu to exit the application. Related Information  Keys Help. ═══ 16.2. Call Nesting Edit Menu ═══ The Edit menu allows you to locate and change text in the Call Nesting diagram. Items you can select from this menu include the following: Find Find a function call, function return, an annotation, or a user event. Find Next Find the next occurrence of the last item you searched for. Annotate Insert comments in your diagram. Select time Go to a specific time in the diagram. Select time range Select all events in a specified time. Select all Select the entire Call Nesting diagram. Related Information  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Keys Help. ═══ 16.2.1. Find Cascading Choice ═══ Select the Find cascading choice to locate text. Items you can select from the cascaded menu include:  Function... for the text of function calls  User Event... to locate user events.  Annotation... to locate annotated text. Related Information  Keys Help. ═══ 16.2.1.1. Function Choice ═══ Select the Function choice to search for functions. When you select the Function choice, the Find Function window appears. Related Information  Keys Help. ═══ 16.2.1.1.1. Find Function Window ═══ Use the Find Function window to search for a specific function in the Call Nesting diagram. You can choose to search when the function was called or returned. Searching for Calls or Returns To search for a function call or return: Note: The Performance Analyzer begins searching at any area that is highlighted and stops at the end of the diagram. To make sure the entire diagram is searched for a particular function, highlight an area at the top of the diagram before you start the search. 1. Select Find... from the Edit menu in the Call Nesting diagram. 2. Select Function... from the cascaded menu, and the Find Function window appears. 3. Do any of the following for the Find string entry field:  Leave the entry field blank and press enter to display a list of all functions in the list box  Enter the file name of the function that you want to display in the list box  Enter the first few characters of the function file name that you want to display in the list box  Enter an asterisk (*) and part or all of the function file name that you want to display in the list box. Note: This is useful when you are searching for a C++ de-mangled function that has class information in front of the function name. Click on the Case sensitive check box to enable case sensitive searching. 4. Select a function from the list box.  Choose to search for when the function was called or returned.  Select the Call radio button to find when a function was called. OR  Select the Return radio button to find when a function returned. 5. Select the appropriate push button to continue:  OK  Cancel  Help Note: The function is highlighted when found. Related Information  Call Nesting Diagram  Find Annotation Window  Find User Event Window  Keys Help. ═══ 16.2.1.2. User Event Choice ═══ Select the User event choice to search for user events. When you select the User event choice, the Find User Event window appears. Related Information  Keys Help. ═══ Find User Event Window ═══ Use the Find User Event... window to search for a specific user event in the Call Nesting diagram. Note: This choice is only available when there are user events or file accesses in the trace file. Find User Event... To search for a user event or file access: Note: The Performance Analyzer begins searching at any area that is highlighted and stops at the end of the diagram. To make sure the entire diagram is searched for a particular user event, highlight an area at the top of the diagram before you start the search. 1. Select Find... from the Edit menu in the Call Nesting diagram. 2. Select User event... from the cascaded menu, and the Find (User Event) window appears. 3. Use the Find string entry field, the Case sensitive check box and the Thread list box in the dialog window to get a list of user events. Note: If you don't know the entire string, you can enter an asterisk (*) with a few characters of the string in the Find string entry field. 4. Select a user event or file access from the list box. 5. Select the appropriate push button to continue:  OK  Cancel  Help. Note: The user event is highlighted when found. Related Information  Call Nesting Diagram  Defining User Events and Creating Prototypes  Find Function Window  Find Annotation Window  Keys Help. ═══ 16.2.1.3. Annotation Choice ═══ Select the Annotation choice to search for annotations. When you select the Annotation choice, the Find Annotation window appears. Related Information  Keys Help. ═══ Find Annotation Window ═══ Use the Find Annotation... window to search for a specific annotation in the Call Nesting diagram. Find Annotation... To search for an annotation: Note: The Performance Analyzer begins searching at any area that is highlighted and stops at the end of the diagram. To make sure the entire diagram is searched for a particular annotation, highlight an area at the top of the diagram before you start the search. 1. Select Find... from the Edit menu in the Call Nesting diagram. 2. Select Annotation... from the cascaded menu, and the Find (Annotation) window appears. 3. Follow the directions in the dialog window to get a list of all annotations. Note: If you don't know the entire annotation, you can enter an asterisk (*) with a few characters of the annotation in the Find string entry field. 4. Select an annotation from the list box. 5. Select the appropriate push button to continue:  OK  Cancel  Help Note: The annotated comment is highlighted when found. Related Information  Call Nesting Diagram  Find Function Window  Find User Event Window  Keys Help. ═══ 16.2.2. Find Next Choice ═══ Select the Find next choice to locate the next instance of the searched text. 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 message box appears if the string cannot be found. Related Information  Call Nesting Diagram Pop-up Menu  Find Function Window  Find User Event Window  Find Annotation Window  Keys Help. ═══ 16.2.3. Annotate... Choice ═══ Select the Annotate... choice to add notes that will appear on the screen, or to change or delete existing annotated text. The annotated comments that are added to the diagram are saved, and will appear on the screen to the right of the function name. When you select the Annotate... choice, an Annotate window appears. Related Information  Call Nesting Selected Item Pop-up Menu  Keys Help. ═══ Annotate Window ═══ Use the Annotate window to add annotated comments to the Call Nesting diagram. The Performance Analyzer saves the comments to the trace file so you can see the comments later. Adding Annotated Comments To add an annotated comment to the diagram: 1. Click on the function where you want to add the comment. 2. Select the Annotation choice from the Edit menu. 3. Type the comment in the window. The comment is limited to 64 characters. 4. Select the appropriate push button to continue:  Add/Change  Remove  Cancel  Help. Deleting Annotated Comments To delete an annotated comment: 1. Click on the comment you want to remove. 2. Select Annotate... from the Edit menu. 3. Remove the comment. Related Information  Find Annotation Window  Defining User Events  Call Nesting Selected Item Pop-up Menu  Keys Help. ═══ 16.2.4. Select Time... Choice ═══ Select the Select time... choice to scroll and select highlighted functions occurring at a specified time. Select the Select time... choice to go to a specific time in the diagram. When you select Select time..., the Select Time window appears. Related Information  Keys Help. ═══ 16.2.4.1. Select Time Window ═══ Use the Select Time window to go to a specific time in the diagram. Going to a Specific Time To select the time: 1. Select the appropriate radio button:  Seconds (s)  Milliseconds (ms)  Microseconds (us) 2. Use the spin buttons to select the time you want to display. 3. Select the appropriate push button to continue:  OK  Cancel  Help. Related Information  Select Time Window  Keys Help. ═══ 16.2.5. Select Time Range... Choice ═══ Select the Select time range... choice to scroll to all highlighted functions. Select the Select time range... choice to chose a specific period of time to view. When you select the Select time range... choice, the Select Time Range window appears. Related Information  Select Time Range Window  Keys Help. ═══ 16.2.5.1. Select Time Range Window ═══ Use the Select Time Range window to view a specific period of time. The Select Time Range window shows you a range of time. Selecting Time Periods To select the time period: 1. In the Start time list box, use the spin buttons to select the start time you want to highlight. 2. To select the time, select the appropriate radio button:  seconds (s),  milliseconds (ms),  microseconds (us). 3. In the End time list box, use the spin buttons to select the end time, where the highlight will stop. 4. To select the time, select the appropriate radio button:  seconds (s),  milliseconds (ms),  microseconds (us). 5. Select the appropriate push button to continue:  OK  Cancel  Help. Related Information  Select Time Window  Keys Help. ═══ 16.2.6. Select All Choice ═══ Select the Select all... choice to select and highlight all functions. Select the Select all choice to highlight the entire diagram. To remove the highlighting, select a specific function. Related Information  Keys Help. ═══ 16.3. Call Nesting View Menu ═══ The View menu allows you to change displayed information. Items you can select from this menu include the following: Include Functions Controls the functions to include or exclude in the diagram. Include Threads. Controls the threads to include or exclude in the diagram. Related Information  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Keys Help. ═══ 16.3.1. Include Functions... Choice ═══ Select the Include functions... choice to list all the functions in the trace file and select one or more for viewing. Note: Any items on the call stack that lead to the selected function will also be displayed. When you select Include functions..., the Include Functions window is displayed. Related Information  Call Nesting Diagram Pop-up Menu  Keys Help. ═══ 16.3.1.1. Include Functions Window ═══ Use the Include Functions window to isolate specific functions or view all functions. This window filters the trace file allowing you to isolate specific areas of interest or areas where problems are occurring. Isolating Specific Functions To include functions: 1. Scroll the list to find the function or functions you want displayed. 2. Highlight each function you want displayed. 3. Select the appropriate push button to continue:  OK  Cancel  Help 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 appropriate push button to continue:  OK  Cancel  Help Viewing A Specific Function 1. To select a specific function, select the Deselect all push button. 2. Select a specific function. 3. Select the appropriate push button to continue:  OK  Cancel  Help Related Information  Call Nesting Diagram Pop-up Menu  Keys Help. ═══ 16.3.2. Include Threads... Choice ═══ Select the Include threads... choice to select which threads are displayed in the diagram. Use the Include threads... choice to filter the trace file, which allows you to isolate specific areas of interest or areas where problems are occurring. When you select Include threads..., the Include Threads window is displayed. Related Information  Call Nesting Diagram Pop-up Menu  Keys Help. ═══ 16.3.2.1. Include Threads Window ═══ Use the Include Threads window to select or isolate specific threads, and to enable and display specific pattern recognitions in the Call Nesting diagram. Use the mouse to highlight your thread selection. You can choose a particular thread or all threads. You can also enable Pattern Recognition from this window. Pattern recognition looks at a single thread and finds patterns of calls and returns. When this choice is enabled, the Call Nesting diagram displays these patterns as a curved arc and the number of repetitions are on the right. Note: Pattern Recognition can only be enabled when a single thread pattern is displayed. When Pattern Recognition is enabled, the Call Nesting diagram will not display annotations. Selecting Specific Threads To select a specific threads: 1. Select the specific threads you want to display. 2. Select the appropriate push button to continue:  OK  Cancel  Help. Displaying Patterns To display the patterns for a thread: 1. Select the specific threads you want to display. 2. Select the Pattern Recognition check box. 3. Select the appropriate push button to continue:  OK  Cancel  Help. Selecting All Threads To select all threads: 1. Highlight All threads to select all threads. 2. Select the appropriate push button to continue:  OK  Cancel  Help Related Information  Call Nesting Diagram Pop-up Menu  Keys Help. ═══ 16.4. Call Nesting Options Menu ═══ The Options menu allows you to customize the Call Nesting diagram and display additional information. 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... Synchronizes other diagrams to display the same highlighted region. Font Selects the font, font style, and font size for the function names. Thread layout Selects the indentation amount for each thread column and draws separator bars between threads. Status Area Area at top of window that describes the diagram. You can select which items will appear in the Status Area. Tool bar Use the Tool bar for a shortcut to other menus. Settings Select to save the current settings or restore the defaults. Save Select to save the current settings. Restore initial defaults Select to restore initial defaults. Related Information  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Call Nesting Diagram Pop-up Menu  Call Nesting Selected Item Pop-up Menu  Keys Help. ═══ 16.4.1. Call Stack... Choice ═══ Select the Call stack... choice to display the hierarchy of function calls in a thread. When you select the Call stack... choice, a Call Stack window appears. Related Information  Call Nesting Selected Item Pop-up Menu  Keys Help. ═══ Call Stack Window ═══ Select the Call Stack window to display the order in which the functions were called at a selected point. Displaying the Call Stack To display a call stack for a function: 1. Click on a function to select it. 2. Select Call Stack from the Options menu. A Call Stack window appears the function you selected and its parents (called functions) in the order in which they were called. 3. Select the appropriate push button to continue:  OK  Help. Related Information  Call Nesting Diagram  Call Nesting Selected Item Pop-up Menu  Keys Help. ═══ 16.4.2. Correlation... Choice ═══ Select the Correlation... choice to show the location of a particular function in the Call Nesting window with other available views. When you select the Correlation... choice, the Correlation window appears. Related Information  Call Nesting Selected Item Pop-up Menu  Keys Help. ═══ 16.4.3. Font... Choice ═══ Select the Font... choice to change the font, font style, and font size for the text area of the Call Nesting window. This choice is available from the Options menu of the Call Nesting window. When you select the Font... choice, the When you select this choice, the Font window appears. The Font window has the following areas: Name entry field Type a font name in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a name from the list. Size entry field Type a font size in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a size from the list. Style entry field Type a font style in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a style from the list. Emphasis check boxes Click on one of these check boxes to outline, underscore, or strikeout text. Sample box This box shows a sample of how text will appear with the settings you have selected. Ok push button Changes the font according to the settings you selected. Reset push button Changes all font settings to the default settings. Cancel push button Closes the window without making changes. Related Information  Call Nesting Diagram Pop-up Menu  Keys Help. ═══ Correlation Window ═══ Use the Correlation window to mark a point in a chronologically-scaled diagram, such as the Call Nesting diagram, Execution Density diagram, or Time Line diagram, and then find that same point in another chronologically-scaled diagram. To correlate two or more diagrams using the Correlation... choice: 1. Open your trace file in a diagram that has correlation capability (Call Nesting, Execution Density, or Time Line). 2. Open at least one other window with a different diagram or the same diagram at a different scale. (You can change a diagram's scale by selecting the Zoom in or Zoom out choice.) 3. Highlight the area between the events of interest in one of the diagrams. To highlight an area: a. Click and hold mouse button one on the first event. b. While holding mouse button one, drag the pointer to the last event. c. Release the mouse button. 4. Select Correlation... from the Options menu. The Correlation window appears. 5. Select the name of each diagram you want to correlate. 6. Select the appropriate push button to continue:  OK  Select all  Deselect all  Cancel  Help. When you select the OK push button, the Performance Analyzer highlights correlated points in the selected diagrams. To correlate two or more diagrams using the drag and drop method: 1. Open your trace file in a diagram that has correlation capability (Call Nesting, Execution Density, or Time Line). 2. Open a second diagram that allows correlation (Call Nesting, Execution Density, or Time Line) or open a second window of the same diagram and change its scale. (You can change the scale by selecting the Zoom in or Zoom out choice.) 3. Highlight the area between the events of interest in one of the diagrams. To highlight an area: a. Click and hold mouse button one on the first event. b. While holding mouse button one, drag the pointer to the last event. c. Release the mouse button. 4. Click and hold mouse button two on the diagram that you highlighted, drag the mouse to the other diagram, and then release the button. The area you highlighted first is highlighted in the other diagram. Related Information  Zoom In Choice  Zoom Out Choice  Call Nesting Diagram  Call Nesting Diagram Pop-up Menu  Execution Density Diagram  Time Line Diagram  Keys Help. ═══ 16.4.4. Thread layout... Choice ═══ Select the Thread layout... choice to arrange the starting placement of multiple threads within the Call Nesting window. When you select Thread layout..., a Thread Layout window appears. Related Information  Call Nesting Diagram Pop-up Menu  Keys Help. ═══ 16.4.4.1. Thread Layout Window ═══ Use the Thread Layout window to control the thread indentation and to control whether separator bars are drawn between the threads. Controlling Indentation and Separator Bars To use the Thread Layout window: 1. Select the spin buttons in the Indents per thread entry field until the value you want displays. The maximum indentation value is 20 pixels. 2. Select the check box to draw separator lines between the threads. A check mark symbol in the box indicates to draw separator bars and an empty box indicates not to draw the separator bars. 3. Select the appropriate push button to continue:  Set  Apply  Cancel  Help. Related Information  Call Nesting Diagram  Time Line Diagram  Call Nesting Diagram Pop-up Menu  Keys Help. ═══ 16.4.5. Status Area... Choice ═══ The Status Area, located at the top of the window, describes the settings of the diagram. Select the Status area... choice to change the appearance of the area at the top of the Call Nesting window. You can select Status area from the Options menu and a Status area When you select the Status area... choice, the Status Area window. appears. Related Information  Keys Help. ═══ 16.4.5.1. Status Area Window ═══ Use the Status Area window to control the area at the top of the window. The check boxes represent the choices in the Status Area that you can show or hide. When you disable the check box the choice is hidden. Likewise, when you enable the check box the choice displays in the Status Area. In each diagram the Status Area displays different information. When you select the Status Area window, the choices in the window change based upon the Status Area of the diagram. Choices from the Status Area include:  Trace Description  Filters Select the appropriate check box to continue. Related Information  Dynamic Call Graph Status Area Window  Execution Density Status Area Window  Time Line Status Area. Window  Keys Help. ═══ 16.4.6. Tool Bar Cascading Choice ═══ Select the Tool bar cascading choice to have the Tool bar display or not display in your window, and to enable and disable the Hover help. The choices from the Tool bar cascaded menu are: Show Choose to either show or hide the Tool bar. Hover Choose to either enable or disable displaying the help text when the mouse pointer hovers over the Tool bar buttons. Related Information  Keys Help. ═══ 16.4.6.1. Tool Bar Show Choice ═══ Select the Show choice from the Tool bar cascaded menu to show the Tool bar in your window. When the Show choice is enabled, a check mark will appear beside the choice. Select the Show choice again to remove the check mark and the Tool bar choice will be disabled. Related Information  Tool Bar Hover Choice  Keys Help. ═══ 16.4.6.2. Tool Bar Hover Choice ═══ Select the Hover choice from the Tool Bar cascaded menu to display the name of the Tool bar function it represents when you position the mouse pointer over the buttons. When the Hover choice is enabled, a check mark will appear beside the choice. Select the Hover choice again to remove the check mark and the Hover choice will be disabled. Related Information  Tool Bar Show Choice  Keys Help. ═══ 16.4.7. Settings Cascading Choice ═══ Select the Settings cascading choice to save changes made to the Call Nesting window or to restore the defaults. The choices from the Settings cascaded menu are: Save Save the current session settings. Restore initial defaults Restore the original settings. Related Information  Save Choice  Restore Initial Defaults Choice  Keys Help. ═══ 16.4.7.1. Save Choice ═══ Select the Save choice to save the current settings. These settings are stored in the ICSPERF.INI file and remain active until that file is erased. To restore the default settings, select the Restore defaults choice. Related Information  Restore Initial Defaults Choice  Keys Help. ═══ 16.4.7.2. Restore Initial Defaults Choice ═══ Select the Restore initial defaults choice to change to the original or default settings. You can select the Save choice to save settings. Related Information  Save Choice  Keys Help. ═══ 16.5. Call Nesting Project Menu ═══ This menu appears when you start the Performance Analyzer from within the WorkFrame environment. The Project menu gives you direct access to all of the actions that you can perform from your current location. When you select the Edit function choice from this menu, the source code for the selected function is displayed in the default editor for WorkFrame's edit action. Related Information  Search Paths Window  Trace Generation Window  Keys Help ═══ 16.5.1. Edit Function Choice ═══ Select the Edit function choice to edit a source file in WorkFrame's default editor. This choice lets you edit the source for a function selected on the Call Nesting diagram. When you are working in the WorkFrame environment, this choice is available from the Project menu on the Call Nesting diagram. It is also available from the Selected Item pop-up menu on the Call Nesting diagram. To locate a source file for editing, the Performance Analyzer must first locate the executable containing the name of the source file. The Performance Analyzer searches the following paths (in the order listed) to locate an executable: 1. Path specified in the Locate Executable window 2. Path specified in the Search path for executable files: entry field of the Search Paths window 3. Directory where the executable was located when the trace file was created 4. The current working directory 5. Path specified by the PATH environment variable. To identify the name of the source file, the Performance Analyzer looks at the debug information in the executable. The Performance Analyzer then searches the following paths (in the order listed) to locate the source file: 1. Path specified in the Locate Source File window 2. Path specified in the Search path for source files: entry field of the Search Paths window 3. Path specified in the compile statement (if provided) 4. Directory where the executable was located when the trace file was created 5. The current working directory 6. Path specified by the INCLUDE environment variable. If, after searching these paths, the Performance Analyzer cannot find the: 1. Executable, it displays the Locate Executable window to let you enter the path where the executable resides. 2. Source file, it displays the Locate Source File window to let you enter the path where the source file resides. Once the source file for a function is located, the file is opened to the first line of the function's code. Notes 1. The Performance Analyzer remembers the paths you enter in the Locate Executable and Locate Source File windows and uses them to look for files the next time you select the Edit function choice. 2. You can specify paths that you want the Performance Analyzer to use by selecting the Search Paths choice in the Options menu on the Performance Analyzer - Window Manager window. The paths you enter are automatically saved for the current session. If you want to save the paths for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Locate Executable Window  Locate Source File Window  Search Paths Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 16.6. Call Nesting Help Menu ═══ The Help menu has the following choices: Help index Displays an index of Help topics. General help Displays Help for the active window. Using help Describes how to use Help. How do I? Displays task Help. Product information Displays information about the Performance Analyzer. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 16.6.1. Help Index Choice ═══ Select the Help index choice to display an alphabetical index of Performance Analyzer Help topics. This choice is available from the Help menu of the Call Nesting diagram. Use the Previous push button to return to the last topic you viewed. Use the Search... push button to locate topics in the index. Use the Print... push button to print a topic. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 16.6.2. General Help Choice ═══ Select the General help choice to display Help information for the active window. This choice is available from the Help menu of the Call Nesting diagram. The online Help panel displayed is the same panel that is displayed when you place your cursor inside the window and press F1. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 16.6.3. Using Help Choice ═══ Select the Using help choice for a description of how to use the IBM Performance Analyzer Help facility. This choice is available from the Help menu of the Call Nesting diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 16.6.4. How Do I? Choice ═══ Select the How do I? choice to display the Performance Analyzer task help. This choice is available from the Help menu of the Call Nesting diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 16.6.5. Product Information Choice ═══ Select the Product information choice to display copyright and version information about the Performance Analyzer application. This choice is available from the Help menu of the Call Nesting diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 16.7. Call Nesting Status Area ═══ The Status Area, located at the top of the window, describes the settings of the diagram. You can select the Status area... choice to change the appearance of the area at the top of the Call Nesting window. When you select the Status area... choice, the Status Area window. appears. The choices in the Status area window include: Trace description Select for a brief description of the trace file. Filters Select to display selected filters. Related Information  Dynamic Call Graph Status Area  Execution Density Status Area  Time Line Status Area  Keys Help. ═══ 16.8. Call Nesting Diagram Pop-up Menu ═══ The pop-up menus allow you to quickly access features that are frequently used. The Call Nesting Diagram Pop-up Menu contains actions that can be applied to the entire diagram and the Call Nesting Selected Item Pop-up Menu contains actions that can be a applied to the highlighted item. To access the Call Nesting Diagram Pop-up Menu, click mouse button two on the background area of the diagram. The menu is displayed with the following choices:  Find  Find next  Include function...  Include threads...  Font...  Thread layout... Related Information  Call Nesting Selected Item Pop-up Menu  Keys Help. ═══ 16.9. Call Nesting Selected Item Pop-up Menu ═══ The pop-up menus allow you to quickly access features that are frequently used. The Call Nesting Selected Item Pop-up Menu contains actions that can be applied to the highlighted item and the Call Nesting Diagram Pop-up Menu contains actions that can be a applied to the entire diagram. To access the Call Nesting Selected Item Pop-up Menu, click mouse button two on the highlighted area of the diagram. The menu is displayed with the following choices:  Annotate...  Call stack...  Correlation...  Edit function Related Information  Call Nesting Diagram Pop-up Menu  Keys Help. ═══ 17. Dynamic Call Graph ═══ Dynamic Call Graph The Dynamic Call Graph is a graphical view of the execution of the target program. The Dynamic Call Graph uses arcs and nodes to represent functions and calls and each one has associated information. See Arcs and Nodes for more detailed information. Colors and sizes of nodes and arcs depict the time spent in the node and the number of calls between nodes. A node represents a function. An arc, which is displayed between a pair of nodes, represents a call from one function to another. Double click on any node for the Function Information window to display additional information. Double click on any arc for the Who Calls Whom window to display additional information. Only calls made during the given execution of the program are displayed. Areas of the Dynamic Call Graph Window The following choices are available from the Dynamic Call Graph menu bar:  Menu Bar Summary The choices available from the Dynamic Call Graph menu bar are: - Trace file - View - Options - Project - Help.  Status Area The Status Area provides information about the following: - Trace Description - Filters - Selected Object Related Information  Call Nesting Diagram  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Analyze Trace Window  Hints and Tips  Keys Help ═══ 17.1. Dynamic Call Graph Arcs and Nodes ═══ Arcs and Nodes Colors and sizes of nodes and arcs depict the time spent in the node and the number of calls between nodes. The time spent in a particular node and the number of calls in an arc are shown in different colors. The following table shows what each color means to nodes and arcs. Node colors are based on the maximum executable time spent in a function. Arc colors are based on the maximum number of calls between pairs of functions. Color and Size representation of Nodes and Arc ┌───────────────┬─────────────────────────┬───────────────┐ │Color │Nodes │Arc │ ├───────────────┼─────────────────────────┼───────────────┤ │Gray │0 - 1/8 │0 - 1/8 │ ├───────────────┼─────────────────────────┼───────────────┤ │Blue │1/8 - 1/4 │1/8 - 1/4 │ ├───────────────┼─────────────────────────┼───────────────┤ │Yellow │1/4 - 1/2 │1/4 - 1/2 │ ├───────────────┼─────────────────────────┼───────────────┤ │Red │1/2 - maximum │1/2 - maximum │ └───────────────┴─────────────────────────┴───────────────┘ Note: The currently selected nodes are surrounded by a green box and the currently selected arcs are shown in green. Dynamic Function Information Functions Double clicking on a function displays a function information dialog which shows you the function name, object name and executable name. Select one of the following buttons:  Select the Who calls me button to display the fully qualified function, listed in the Function Information window, and functions that called it.  Select the Whom do I call button to display the fully qualified function, listed in the Function Information window and functions that it called. Arcs Double clicking on an arc displays an arc information dialog window which shows fully qualified function names of the nodes involved with this call. Select one of the following buttons:  Select the Find caller button to display the function that originated the call. The originating caller is displayed in the center of the Dynamic Call Graph.  Select the Find callee button to display the function called by the originating caller. The called function is displayed in the center of the Dynamic Call Graph. Related Information  Dynamic Call Graph  Dynamic Call Graph Status Area  Keys Help. ═══ 17.2. Dynamic Call Graph Trace File Menu ═══ The following choices are available from the Dynamic Call Graph Trace file menu: Open as Shows a new or an additional diagram. Printer settings... Allows you to choose printer settings for your output. Print selected region... Prints the information that is displayed in the current window. Window Manager Displays the Window Manager Exit Performance Analyzer Exits the Performance Analyzer. Related Information  Analyze Trace Window  Call Nesting Diagram  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Keys Help. ═══ 17.2.1. Open As Cascading Choice ═══ Select the Open as choice to view another diagram. You can open as many new windows as you want. To select a new diagram: 1. Select Open as from the Trace file menu. A cascaded menu is displayed with the following choices: Call Nesting Dynamic Call Graph Execution Density Statistics Time Line 2. Select the name of the diagram you want to view. A new window opens and displays the diagram you selected. Related Information  Selecting a Trace File to Analyze  Keys Help. ═══ 17.2.1.1. Call Nesting Choice ═══ The Call Nesting choice is available from the Open as cascaded menu. When you select Call Nesting, the Call Nesting Diagram displays. Related Information  Open As Choice  Keys Help. ═══ 17.2.1.2. Dynamic Call Graph Choice ═══ The Dynamic Call Graph choice is available from the Open as cascaded menu. When you select Dynamic Call Graph, the Dynamic Call Graph displays. Related Information  Open As Choice  Keys Help. ═══ 17.2.1.3. Execution Density Choice ═══ The Execution Density choice is available from the Open as cascaded menu. When you select Execution Density, the Execution Density diagram displays. Related Information  Open As Choice  Keys Help. ═══ 17.2.1.4. Statistics Choice ═══ The Statistics choice is available from the Open as cascaded menu. When you select Statistics, the Statistics Diagram displays. Related Information  Open As Choice  Keys Help. ═══ 17.2.1.5. Time Line Choice ═══ The Time Line choice is available from the Open as cascaded menu. When you select Time Line, the Time Line diagram displays. Related Information  Open As Choice  Keys Help. ═══ 17.2.2. Printer Settings... Choice ═══ Select the Printer settings... choice to select settings for your print jobs. When you select the Printer settings... choice, the Printer Settings window appears.  OK  Font  Job  Cancel  Help Related Information  Keys Help. ═══ 17.2.3. Print Selected Region... Choice ═══ Select the Print selected region... choice to print the information from the Dynamic Call Graph. To print the Dynamic Call Graph, select the Print selected region... choice from the Trace file menu. The Print Selected Region window appears. Related Information  Keys Help. ═══ 17.2.4. Window Manager Choice ═══ Select the Window Manager choice to display the Window Manager window. Related Information  Performance Analyzer - Window Manager  Keys Help. ═══ 17.2.5. Exit Performance Analyzer Choice ═══ Select Exit Performance Analyzer to close Performance Analyzer and all windows. Related Information  Keys Help. ═══ 17.3. Dynamic Call Graph View Menu ═══ The following choices are available from the View menu: Include threads Controls the threads to include or exclude in the diagram. Overview Use to navigate through large diagrams quickly. Zoom in Enlarges the size of the diagram without changing the size of the window. Zoom out Decreases the size of the diagram without changing the size of the window. Re-lay Sizes to fit all of the diagram in the window. Restore Restores nodes to the diagram to show the default view. Related Information  Call Nesting Diagram  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Keys Help. ═══ 17.3.1. Include Threads... Choice ═══ Select the Include threads... choice to select which threads are displayed in the diagram. Use the Include threads... choice to filter the trace file, which allows you to isolate specific areas of interest or areas where problems are occurring. When you select this choice, an Include Threads window appears. Related Information  Keys Help. ═══ 17.3.1.1. Include Threads Window ═══ Use the Include Threads window to select or isolate specific threads in the Dynamic Call Graph. Use the mouse to highlight your thread selection. You can choose any thread or a combination of threads. Note: The percentages are based upon the total execution time of the selected threads, not the total execution time. When you change the threads you affect the percentages. Selecting Specific Threads To select a specific thread: 1. Select the specific threads you want to display. 2. Select the appropriate push button to continue:  OK  Select all  Deselect all  Cancel  Help. Selecting All Threads To select all threads: 1. Highlight All threads to select all threads. 2. Select the appropriate push button to continue:  OK  Select all  Deselect all  Cancel  Help Related Information  Dynamic Call Graph  Execution Density Diagram  Analyze Trace Window  Keys Help. ═══ 17.3.2. Overview Choice ═══ Select the Overview choice to display a scaled-down image of the diagram you are viewing. When you select the Overview choice, the Overview dialog window appears. The Overview window lets you navigate through large diagrams. Switching Views To change the view of the diagram, use the following to: 1. View a larger or smaller area of the diagram. Press and hold mouse button one while pointing to any edge of the shaded rectangle in the Overview window. By moving the mouse, 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 diagram. Press and hold mouse button one in the center of the shaded rectangle in the Overview window. Move the rectangle over the part of diagram that you want to view. When you release mouse button one, the main window is redrawn to reflect the new view. Related Information  Dynamic Call Graph  Keys Help. ═══ Overview Window ═══ Use the Overview window to display a scaled-down image of the Dynamic Call Graph. The Overview window lets you navigate through large trace files. Switching Views To view a larger or smaller area of the Dynamic Call 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. 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 diagram that you want to view. When you release mouse button one, the main window is redrawn to reflect the new view. Related Information  Dynamic Call Graph  Analyze Trace Window.  Keys Help. ═══ 17.3.3. Zoom In Choice ═══ Select the Zoom in choice to enlarge the diagram without changing the window size. The Zoom in choice makes the selected object appear closer and makes the diagram appear larger in the window. If a node or an arc is selected, 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 diagram, select Zoom in from the View menu or press the Ctrl and the + key. Each time you select Zoom in from the View menu or press Ctrl and the + key, the window appears a larger view of the diagram. To return the diagram to the original size, use the Re-lay choice in the View menu. Related Information  Zoom Bar  Zoom Out Choice  Keys Help. ═══ 17.3.4. Zoom Out Choice ═══ Select the Zoom out choice to decrease the size of the diagram so the entire diagram can be displayed without changing the window size. The Zoom out choice makes the selected object appear further away making the diagram appear smaller in the window. The original default view is the smallest that the graph can be displayed. To decrease the view of the diagram, select Zoom out from the View menu or press the Ctrl key and the + key. Each time you select Zoom out from the View menu or press the Ctrl key and the - key, the window appears a smaller view of the diagram. To return the diagram to the original size, use the Re-lay choice in the View menu. Related Information  Zoom Bar  Zoom In Choice  Keys Help. ═══ 17.3.5. Re-lay Choice ═══ Select the Re-lay choice to center and resize the nodes. See Dynamic Call Graph for more information about isolating nodes and arcs. To re-lay the diagram, select Re-lay from the View menu. The diagram is centered in the window with all selected elements sized to fit. Related Information  Zoom Bar  Restore Choice  Keys Help. ═══ 17.3.6. Restore Choice ═══ Select the Restore choice to return the diagram to the default view. To restore a diagram, select Restore from the View menu. The entire diagram is restored to the default view and all nodes and arcs are visible in the window. Related Information  Zoom Bar  Re-lay Choice  Keys Help. ═══ 17.4. Dynamic Call Graph Options Menu ═══ The Options menu allows you to customize the Dynamic Call Graph and display additional information. The following choices are available from the Options menu: Scale node sizes Scales node sizes. Find function Searches for functions in the diagram. Status area Area at the top of the window describes the diagram. Tool bar Use the Tool bar for a shortcut to other menus. Settings Saves the current settings or restores the default settings. Related Information  Call Nesting Diagram  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Keys Help. ═══ 17.4.1. Scale Node Sizes Choice ═══ Select the Scale node sizes choice to choose how you want to display the diagram. When you enable the Scale node size function a check mark appears beside the menu choice, and the arcs and nodes are then displayed in proportion to the execution and active time. To disable the Scale node size function, click on it again to remove the check mark. Related Information  Analyze Trace Window  Execution Density Diagram Pop-up Menu  Keys Help. ═══ 17.4.2. Find Function... Choice ═══ Select the Find function... choice to search for a function in the diagram. When you select the Find function... choice, the Find Function window appears. Related Information  Keys Help. ═══ Find Function Window ═══ Use the Find function window to search for a specific function in the diagram. Finding a Function To find a function: 1. Do any of the following for the Find string entry field:  Leave the entry field blank and press enter to display a list of all functions in the list box  Enter the file name of the function that you want to display in the list box  Enter the first few characters of the function file name that you want to display in the list box  Enter an asterisk (*) and part or all of the function file name that you want to display in the list box. Note: This is useful when you are searching for a C++ de-mangled function that has class information in front of the function name. Click on the Case sensitive check box to enable case sensitive searching. 2. Select a function from the list box. 3. Select the appropriate push button to continue:  OK  Cancel  Help Note: The function is highlighted and centered when found. Related Information  Keys Help. ═══ 17.4.3. Status Area... Choice ═══ Select the Status area... choice to change the appearance of the area at the top of the Dynamic Call Graph window. The Status area includes:  Trace Description  Filters  Selected Object When you select Status area, the Status Area window appears. Related Information  Keys Help. ═══ 17.4.3.1. Status Area Window ═══ Use the Status Area window to control the area at the top of the window. The check boxes represent the choices in the Status Area that you can show or hide or display. When you disable the check box the choice is hidden. Likewise, when you enable the check box the choice displays in the Status Area. In each diagram the Status Area displays different information. When you select the Status Area window, the choices in the window change based upon the Status Area of the diagram. Choices from the Status Area include:  Trace Description  Filters  Selected Object Select the appropriate check box to continue. Related Information  Call Nesting Status Area Window  Execution Density Status Area Window  Time Line Status Area Window.  Keys Help. ═══ 17.4.4. Tool Bar Cascading Choice ═══ Select the Tool bar cascading choice to have the Tool bar display or not display in your window, and to enable and disable the Hover help. The choices from the Tool bar cascaded menu are: Show Choose to either show or hide the Tool bar. Hover Choose to either enable or disable displaying the help text when the mouse pointer hovers over the Tool bar buttons. Related Information  Keys Help. ═══ 17.4.5. Settings Cascading Choice ═══ The choices from the Settings cascaded menu allow you to save current settings or switch to the original settings. Save Save the current session settings. Restore initial defaults Restore the original settings. Related Information  Save Choice  Restore Initial Defaults Choice  Keys Help. ═══ 17.4.5.1. Save Choice ═══ Select the Save choice to save the current settings. These settings are stored in the ICSPERF.INI file and remain active until that file is erased. To restore the default settings, select the Restore initial defaults choice. Related Information  Restore Initial Defaults Choice  Keys Help ═══ 17.4.5.2. Restore Initial Defaults Choice ═══ Select the Restore initial defaults choice to change to the original or default settings. You can select the Save choice to save settings. Related Information  Save Choice  Keys Help ═══ 17.5. Dynamic Call Graph Project Menu ═══ This menu appears when you start the Performance Analyzer from within the WorkFrame environment. The Project menu gives you direct access to all of the actions that you can perform from your current location. When you select the Edit function choice from this menu, the source code for the selected function is displayed in the default editor for WorkFrame's edit action. Related Information  Search Paths Window  Trace Generation Window  Keys Help ═══ 17.5.1. Edit Function Choice ═══ Select the Edit function choice to edit a source file in WorkFrame's default editor. This choice lets you edit the source for a function selected on the Dynamic Call Graph. When you are working in the WorkFrame environment, this choice is available from the Project menu on the Dynamic Call Graph. To locate a source file for editing, the Performance Analyzer must first locate the executable containing the name of the source file. The Performance Analyzer searches the following paths (in the order listed) to locate an executable: 1. Path specified in the Locate Executable window 2. Path specified in the Search path for executable files: entry field of the Search Paths window 3. Directory where the executable was located when the trace file was created 4. The current working directory 5. Path specified by the PATH environment variable. To identify the name of the source file, the Performance Analyzer looks at the debug information in the executable. The Performance Analyzer then searches the following paths (in the order listed) to locate the source file: 1. Path specified in the Locate Source File window 2. Path specified in the Search path for source files: entry field of the Search Paths window 3. Path specified in the compile statement (if provided) 4. Directory where the executable was located when the trace file was created 5. The current working directory 6. Path specified by the INCLUDE environment variable. If, after searching these paths, the Performance Analyzer cannot find the: 1. Executable, it displays the Locate Executable window to let you enter the path where the executable resides. 2. Source file, it displays the Locate Source File window to let you enter the path where the source file resides. Once the source file for a function is located, the file is opened to the first line of the function's code. Notes 1. The Performance Analyzer remembers the paths you enter in the Locate Executable and Locate Source File windows and uses them to look for files the next time you select the Edit function choice. 2. You can specify paths that you want the Performance Analyzer to use by selecting the Search Paths choice in the Options menu on the Performance Analyzer - Window Manager window. The paths you enter are automatically saved for the current session. If you want to save the paths for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Locate Executable Window  Locate Source File Window  Search Paths Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 17.6. Dynamic Call Graph Help Menu ═══ The Help menu has the following choices: Help index Displays an index of Help topics. General help Displays Help for the active window. Using help Describes how to use Help. How do I? Displays task Help. Product information Displays information about the Performance Analyzer. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 17.6.1. Help Index Choice ═══ Select the Help index choice to display an alphabetical index of Performance Analyzer Help topics. This choice is available from the Help menu of the Dynamic Call Graph. Use the Previous push button to return to the last topic you viewed. Use the Search... push button to locate topics in the index. Use the Print... push button to print a topic. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 17.6.2. General Help Choice ═══ Select the General help choice to display Help information for the active window. This choice is available from the Help menu of the Dynamic Call Graph. The online Help panel displayed is the same panel that is displayed when you place your cursor inside the window and press F1. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 17.6.3. Using Help Choice ═══ Select the Using help choice for a description of how to use the IBM Performance Analyzer Help facility. This choice is available from the Help menu of the Dynamic Call Graph. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 17.6.4. How Do I? Choice ═══ Select the How do I? choice to display the Performance Analyzer task help. This choice is available from the Help menu of the Dynamic Call Graph. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 17.6.5. Product Information ═══ Select the Product information choice to display copyright and version information about the Performance Analyzer application. This choice is available from the Help menu of the Dynamic Call Graph. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 17.7. Dynamic Call Graph Status Area ═══ The Status Area, located at the top of the window, describes the settings of the diagram. You can select the Status area choice to change the appearance of the area at the top of the Dynamic Call Graph window. When you select the Status area... choice,the Status Area window appears. The choices in the Status area window include: Trace description Select for a brief description of the trace file. Filters Select to display selected filters. Selected object Select to display selected object. Note: If you highlight a node, a function name is displayed. If you highlight an arc, a function call is displayed. Related Information  Call Nesting Status Area  Execution Density Status Area  Time Line Status Area  Keys Help ═══ 17.8. Dynamic Call Graph Zoom Bar ═══ There are several ways to zoom in the Dynamic Call Graph window. When zooming in and out, the Dynamic Call Graph takes the selected node or arc that is highlighted, and uses it as the focal point. Zooming in the Dynamic Call Graph You can use the:  Zoom in choice from the View menu to change the diagram view. When zooming in, your view is a step closer to the selected object and the object in the window appears larger.  Zoom out choice from the View menu to change the diagram view. When zooming out, your view is a step further away from the selected object and the object in the window appears smaller.  Zoom bar in the Dynamic Call Graph window by sliding the arm up or down, to change the diagram view.  Re-lay choice from the View menu to return to the original diagram view.  Overview choice from the View menu to quickly move around in the viewing area of the diagram. The Overview choice provides you with another option of viewing. Use it to move quickly to other areas of the diagram when zooming in and out. When using the Overview choice, you have a miniature version of the Dynamic Call Graph window. The gray box highlights the area currently in view in the window. Moving the small gray box around in the Overview window allows you to change the view in the Dynamic Call Graph window quickly. You can also grab the sides of the gray box to resize the area being shown in the diagram window. Related Information - Zoom In Choice - Zoom Out Choice - Dynamic Call Graph - Keys Help. ═══ 17.9. Dynamic Call Graph Function Information Window ═══ Use the Function Information window to display information about:  a selected function  the total execution time in seconds and percentages  active time in seconds and percentages,  which function called the selected function and  the functions that the selected function called. Displaying the Function Information Window To display the Function Information window: Double-click on a node using mouse button one. Using the Function Information Window The name of the function appears on the left side of the split bar area. The object file and executable name appear on the right side of the split bar area. The following information is provided in the Function Information Window:  Execution time (in time and percentage)  Time on stack (in time and percentage)  Number of calls 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 diagram, 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. Cancel Closes the window. Help Displays Help. Note: If the trace file does not have time stamps,  the Execution Time and Time on stack will not be displayed.  the nodes will all be displayed in the same color and size. and  the Scale node sizes choice will be disabled. Related Information  Who Calls Whom Window  Dynamic Call Graph  Analyze Trace Window.  Keys Help. ═══ 17.10. Dynamic Call Graph Who Calls Whom Window ═══ Use the Who Calls Whom window to display information about a selected arc. To display the Who Calls Whom window, double-click on an arc. Using the Who Calls Whom Window The Who Calls Whom window shows the name of the calling function, the called function, and the number of times the call is made. The calling function field and the called function field each have a split bar function between the function name and the object file and executable name. Use the split bar to change the size of the left or right field in either the calling function or the called function fields. The following lists the push buttons and how to use each one: 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 Closes the window. Related Information  Function Information Window  Dynamic Call Graph  Analyze Trace Window.  Keys Help. ═══ 18. Execution Density Diagram ═══ Execution Density Diagram The Execution Density diagram shows trends of program execution by displaying the trace data chronologically from top to bottom as thin horizontal lines of various colors in different columns. The Execution Density diagram consists of columns which contain thin lines of various colors. The following list describes the diagram components:  Each vertical column represents a function.  The thickness of each line represents a unit of time called a time slice.  The color of each line represents the percentage of program execution time spent in the given function for that time slice. Note: Only selected threads are used in calculating this percentage. For instance, in the default setting, functions executing more than 50 percent of a given time slice have a red line drawn in the appropriate column at the vertical location corresponding to the time slice. See Color window for more information about how the color is determined and how you can change the colors and percentages that are used. The trace is displayed at 100 percent magnification. You can magnify or filter the diagram to change the amount of detail displayed. See Filters for more information about filtering and magnifying. Note: 1. When a thread switch occurs in the Execution Density diagram, the time between the last recorded event in the previous thread and the first event in the new thread will be allotted to the previous thread. 2. Events that take small amounts of time might be hard to distinguish until the magnification has been increased. See Filters for more information about changing the scale of the pages. Areas of the Execution Density Window The following topics describe the areas of the Execution Density diagram:  Menu Bar Summary The choices available from the Execution Density diagram menu bar are: - Trace file - Edit - View - Options - Project - Help.  Status Area The Status Area provides information about the following: - Trace Description - Time Slice - Selected Region - Filters - Selected Object  Current Column Indicator  Vertical Ruler  Execution Density Pop-up Menus - Execution Density Diagram Pop-up Menu. - Execution Density Selected Item Pop-up Menu. Related Information  Call Nesting Diagram  Dynamic Call Graph  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 18.1. Execution Density Trace File Menu ═══ The following choices are available from the Execution Density Trace file menu: Open As Choice Shows a new or an additional diagram. Printer settings... Allows you to choose printer settings for your output. Print selected region... Prints a selected area of the diagram. Window Manager Displays the Window Manager. Exit Performance Analyzer Exits the Performance Analyzer. Related Information  Analyze Trace Window  Call Nesting Diagram  Dynamic Call Graph  Statistics Diagram  Time Line Diagram  Keys Help. ═══ 18.1.1. Open As Cascading Choice ═══ Select the Open as choice to view another diagram. You can open as many new diagram windows as you want. To select a new diagram: 1. Select Open as from the Trace file menu. A cascaded menu is displayed with the following choices: Call Nesting Dynamic Call Graph Execution Density Statistics Time Line 2. Select the name of the diagram you want to view. A new window opens and displays the diagram you selected. Related Information  Selecting a Trace File to Analyze  Keys Help. ═══ 18.1.1.1. Call Nesting Choice ═══ The Call Nesting choice is available from the Open as cascaded menu. When you select Call Nesting, the Call Nesting Diagram displays. Related Information  Open As Choice  Keys Help. ═══ 18.1.1.2. Dynamic Call Graph Choice ═══ The Dynamic Call Graph choice is available from the Open as cascaded menu. When you select Dynamic Call Graph, the Dynamic Call Graph displays. Related Information  Open As Choice  Keys Help. ═══ 18.1.1.3. Execution Density Choice ═══ The Execution Density choice is available from the Open as cascaded menu. When you select Execution Density, the Execution Density Diagram diagram displays. Related Information  Open As Choice  Keys Help. ═══ 18.1.1.4. Statistics Choice ═══ The Statistics choice is available from the Open as cascaded menu. When you select Statistics, the Statistics Diagram displays. Related Information  Open As Choice  Keys Help. ═══ 18.1.1.5. Time Line Choice ═══ The Time Line choice is available from the Open as cascaded menu. When you select Time Line, the Time Line diagram displays. Related Information  Open As Choice  Keys Help. ═══ 18.1.2. Printer Settings... Choice ═══ Select the Printer settings... choice to select settings for your print jobs. When you select the Printer settings... choice, the Printer Settings window appears.  OK  Font  Job  Cancel  Help Related Information  Keys Help. ═══ 18.1.3. Print Selected Region... Choice ═══ Select the Print selected region... choice to print a selected area of the Execution Density diagram. To print an area of the Execution Density diagram, highlight the area and then select this choice from the Trace file menu. The Print Selected Region window appears. Related Information  Keys Help. ═══ 18.1.4. Window Manager Choice ═══ Select the Window manager choice to display the Window Manager window. Related Information  Performance Analyzer - Window Manager  Keys Help. ═══ 18.1.5. Exit Performance Analyzer ═══ Select Exit Performance Analyzer to close the Performance Analyzer and all the active windows. Related Information  Keys Help. ═══ 18.2. Execution Density Edit Menu ═══ The Edit menu allows you to locate and change text in the Execution Density diagram. Items you can select from this menu include the following: Find function Search for a function. Find Next Find the next occurrence of the last item you searched for. Select time Go to a specific time in the diagram. Select time range Select a specified time in the diagram. Select all Select the entire Execution Density diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Statistics Diagram  Time Line Diagram  Keys Help. ═══ 18.2.1. Find Function... Choice ═══ Select the Find function... choice to search for a function call or return. When you select the Find function... choice, the Find Function window appears. Related Information  Execution Density Diagram Pop-up Menu  Keys Help. ═══ Find Function Window ═══ Use the Find function window to search for a specific function in the diagram. You can choose to search when the function was called or returned. Searching for Calls or Returns To search for a function call or return: 1. Do any of the following for the Find string entry field:  Leave the entry field blank and press enter to display a list of all functions in the list box  Enter the file name of the function that you want to display in the list box  Enter the first few characters of the function file name that you want to display in the list box  Enter an asterisk (*) and part or all of the function file name that you want to display in the list box. Note: This is useful when you are searching for a C++ de-mangled function that has class information in front of the function name. Click on the Case sensitive check box to enable case sensitive searching. 2. Select a function from the list box.  Choose to search for when the function was called or returned.  Select the Call radio button to find when a function was called. OR  Select the Return radio button to find when a function returned. 3. Select the appropriate push button to continue:  OK  Cancel  Help Note: The function is highlighted when found. Related Information  Find Next Choice  Keys Help. ═══ 18.2.2. Find Next Choice ═══ Select the Find next choice to locate the next instance of the searched text. To find the next occurrence, select Find next from the Edit menu. The string is highlighted when found. A message box appears if the string cannot be found. Related Information  Execution Density Diagram Pop-up Menu  Keys Help. ═══ 18.2.3. Select Time... Choice ═══ Select the Select time... choice to go to a specific time in the diagram. When you select the Select time... choice, the Select Time window appears. Related Information  Select Time Range Window  Analyze Trace Window  Keys Help. ═══ Select Time Window ═══ Use the Select Time window to go to a specific time in the diagram. Going to a Specific Time To select the time: 1. Select the appropriate radio button:  seconds (s)  milliseconds (ms)  microseconds (us) 2. Use the spin buttons to select the time you want to display. 3. Select the appropriate push button to continue:  OK  Cancel  Help. Related Information  Select Time Range Window  Call Nesting Diagram  Execution Density Diagram  Time Line Diagram.  Keys Help. ═══ 18.2.4. Select Time Range... Choice ═══ Select the Select time... choice to chose to view a specific time period. When you select the Select time... choice, the Select Time Range window appears. Related Information  Select Time Window  Analyze Trace Window  Keys Help. ═══ Select Time Range Window ═══ Use the Select Time Range window to view a specific period of time. Selecting Time Periods To select the time period: 1. In the Start time list box, use the spin buttons to select the start time you want to highlight. 2. To select the time, select the appropriate radio button:  seconds (s),  milliseconds (ms),  microseconds (us). 3. In the End time list box, use the spin buttons to select the end time, where the highlight will stop. 4. To select the time, select the appropriate radio button:  seconds (s),  milliseconds (ms),  microseconds (us). 5. Select the appropriate push button to continue:  OK  Cancel  Help. Related Information  Call Nesting Diagram  Execution Density Diagram  Time Line Diagram  Analyze Trace Window  Select Time Window.  Keys Help. ═══ 18.2.5. Select All Choice ═══ Select the Select all choice to highlight the entire diagram. To remove the highlighting, select a specific function. Related Information  Select Time Window  Select Time Range Window  Keys Help. ═══ 18.3. Execution Density View Menu ═══ The choices available from the View menu are: Zoom In Magnifies the Execution Density diagram to view a region of interest. Zoom Out Reduces the Execution Density diagram. Zoom to selected range Magnifies an area of interest. Scale pages Controls the number of pages the diagram uses. Include functions Isolates specific functions to view in your program. Include threads Selects which threads are displayed in the diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Statistics Diagram  Time Line Diagram  Keys Help. ═══ 18.3.1. Zoom In Choice ═══ Select the Zoom In choice to magnify the Execution Density diagram. Selecting the Zoom In choice will magnify the Execution Density diagram by a factor of 5. The point in the trace file at the top of the current page will remain fixed, resulting in the view changing to show the top one fifth of the previously displayed page. If the diagram is already scaled to its maximum, this choice will be disabled. Note: If the diagram is scaled within a factor of 5 of the maximum magnification, this choice will bring the diagram to its full magnification. The Zoom In choice is offered in both the View menu and the Execution Density Diagram Pop-up Menu Also, holding the Ctrl key and pressing the + key will perform the same function. Related Information  Zoom Out Choice  Zoom to Selected Range Choice  Execution Density Selected Item Pop-up Menu  Keys Help. ═══ 18.3.2. Zoom Out Choice ═══ Select the Zoom Out choice to reduce the magnification of the Execution Density diagram. Selecting the Zoom Out choice will decrease the magnification of the Execution Density diagram by a factor of 5. The point in the trace file at the top of the current page will remain fixed, resulting in the view changing to display the previously displayed page in the top one fifth of the new view. If necessary, the diagram will adjust to ensure that time past the end of the trace file is not displayed. If the diagram is already scaled to its minimum magnification, this choice will be disabled. Note: If the diagram is scaled within a factor of 5 of the minimum magnification, this choice will bring the diagram to a full 100 % view. The Zoom Out choice is offered in both the View menu and the Execution Density Pop-up Menu Also, holding the Ctrl key and pressing the - key will perform the same function. Related Information  Zoom In Choice  Zoom to Selected Range Choice  Execution Density Selected Item Pop-up Menu  Keys Help. ═══ 18.3.3. Zoom to Selected Range Choice ═══ Select the Zoom to selected range to magnify an area of interest in the Execution Density diagram. To magnify a range of interest, highlight the range using the mouse or the Select time range... choice and select Zoom to selected range from the View menu. The scale of the diagram will be expanded so that the highlighted area fills the entire display. Note: When the magnification is at its maximum, the choice will be disabled. Also, if it is impossible to magnify the diagram to the degree required to stretch the highlighted region across the entire diagram, the highest possible magnification will be used. Shortcut Method After highlighting the area of interest, use mouse button two to click on the highlighted area. From the displayed Selected Item Pop-up Menu, choose Zoom to selected range. Related Information  Zoom In Choice  Zoom Out Choice  Execution Density Selected Item Pop-up Menu  Keys Help. ═══ 18.3.4. Scale Pages... Choice ═══ Select the Scale pages... choice to choose how many pages you want used to display the diagram. When you select the Scale pages... choice, a Scale pages window appears. Related Information  Analyze Trace Window  Execution Density Diagram Pop-up Menu  Keys Help. ═══ Scale Pages Window ═══ Use the Scale Pages window to choose how much time is shown in the time slice. When you allow more pages, the diagram shows more detailed information. When you reduce the pages, the diagram shows less detailed information. Note: Scaling adjusts the number that you select to get an integral number of full screens. The Performance Analyzer shows the total execution time for your program above the slider. 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 width of the current window. Scaling the Pages To scale the pages in the diagram, do the following: 1. Use the slider to set the number of pages:  Move the slider arm to the Maximum position to increase the number of pages in the diagram.  Move the slider arm to the Minimum position to decrease the number of pages in the diagram. Note: When you move the slider arm, the page number changes to show the new selection. Additionally, the Tics per row and Approximate time slice values change to display the new settings. 2. Select the appropriate push button to continue:  OK  Cancel  Help. Related Information  Analyze Trace Window  Execution Density Diagram  Time Line Diagram.  Keys Help. ═══ 18.3.5. Include Functions... Choice ═══ Select the Include functions... choice to isolate specific functions to view in your program. This choice filters the trace file allowing you to isolate specific areas of interest or areas where problems are occurring. When you select the Include functions... choice, an Include Functions window appears. Related Information  Analyze Trace Window  Execution Density Diagram Pop-up Menu  Keys Help. ═══ Include Functions Window ═══ Use the Include Functions window to isolate specific functions or view all functions. This window filters the trace file allowing you to isolate specific areas of interest or areas where problems are occurring. Isolating Specific Functions To include functions: 1. To include a specific function, select the Deselect 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 appropriate push button to continue:  OK  Cancel  Help Viewing All Functions 1. To select all functions, select the Select all push button. 2. Select the appropriate push button to continue:  OK  Cancel  Help Related Information  Call Nesting Diagram  Execution Density Diagram  Dynamic Call Graph  Analyze Trace Window.  Keys Help. ═══ 18.3.6. Include Threads... Choice ═══ Select the Include threads... choice to select which threads are displayed in the diagram. When you select the Include threads... choice, an Include Threads window appears. The Include Threads window allows you to isolate specific threads in your program or show all threads. This choice filters the trace file allowing you to isolate specific areas of interest or areas where problems are occurring. Related Information  Analyze Trace Window  Execution Density Diagram Pop-up Menu  Keys Help. ═══ 18.3.6.1. Include Threads Window ═══ Use the Include Threads window to select or isolate specific threads, and to enable and display specific pattern recognitions in the Execution Density diagram. Use the mouse to highlight your thread selection. You can choose a particular thread or all threads. Note: The percentages are based upon the total execution time of the selected threads, not the total execution time. When you change the threads you affect the percentages. Selecting Specific Threads To select a specific thread: 1. Select the specific threads you want to display. 2. Select the appropriate push button to continue:  OK  Select all  Deselect all  Cancel  Help. Selecting All Threads To select all threads: 1. Highlight All threads to select all threads. 2. Select the appropriate push button to continue:  OK  Select all  Deselect all  Cancel  Help Related Information  Dynamic Call Graph  Execution Density Diagram  Analyze Trace Window  Keys Help. ═══ 18.4. Execution Density Options Menu ═══ The Options menu allows you to customize the Execution Density diagram and display additional information. The following choices are available from the Options menu: Color Selects the colors used to display the percentage of time used by each function and the percentage of time each color represents. Column width Controls the width (in pixels) for each function column in the diagram. Correlation... Synchronizes other diagrams to display the same highlighted region. Status area Control the gray area at the top of the window. Tool bar Use the Tool bar for a shortcut to other menus. Settings Saves the current settings or restores the defaults. Related Information  Call Nesting Diagram  Dynamic Call Graph  Statistics Diagram  Time Line Diagram  Keys Help. ═══ 18.4.1. Color... Choice ═══ Select the Color... choice to control the colors that are used in the diagram, and their meaning. Each color represents a range of percentages consumed by a function, across all threads, in a single time slice. When you select the Color... choice, a Color window displays. Related Information  Execution Density Diagram Pop-up Menu  Keys Help. ═══ Color Window ═══ Use the Color window to show 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. Color Percent range Blue 0 to 1.9 Dark cyan 2 to 4.9 Cyan 5 to 9.9 Pale gray 10 to 24.9 Pink 25 to 49.9 Red 50 to 100 You can change the color and the percentage time each color represents. Setting Time Slice Colors To change the colors used, do the following: 1. Select a spin button under Threshold Percentages to change the time percentage that each color represents. 2. Select a spin button to the right of the color fields to change the colors. 3. Select the appropriate push button to continue:  OK  Cancel  Help 4. To restore the initial defaults, select the Settings choice from the Options menu, then select Restore initial defaults. Related Information  Execution Density Diagram.  Hints and Tips  Keys Help. ═══ 18.4.2. Column Width... Choice ═══ Select the Column width... choice to change the width of the displayed columns. This width can vary between 3 and 32, and the default is 16. Using this choice, along with changing the Scale Pages dialog, can either bring fine details into broader view, or allow you to see larger patterns and more information. When you select the Column width... choice, the Column Width window appears. Related Information  Execution Density Diagram Pop-up Menu  Keys Help. ═══ Column Width Window ═══ Use the Column Width window to choose the width of the displayed columns. Use this window to enhance the display and see the details of the trace file. Changing the Columns Width To change the width of the columns: 1. Use the spin buttons to change the numbers. You can set the number between 3 and 32 pixels 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. 2. Select the appropriate push button to continue:  OK  Cancel  Help. Related Information  Execution Density Diagram.  Keys Help. ═══ 18.4.3. 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. When you select the Correlate... choice, the Correlation window appears. Related Information  Execution Density Selected Item Pop-up Menu  Analyze Trace Window  Keys Help. ═══ 18.4.4. Status Area... Choice ═══ Select the Status area... choice to control the area at the top of the window. When you select the Status area... choice, the Status Area window appears. Related Information  Execution Density Status Area  Keys Help. ═══ 18.4.4.1. Status Area Window ═══ Use the Status Area window to control the area at the top of the window. The check boxes represent the choices in the Status Area that you can show or hide. When you disable the check box the choice is hidden. Likewise, when you enable the check box the choice displays in the Status Area. In each diagram the Status Area displays different information. When you select the Status Area window, the choices in the window change based upon the Status Area of the diagram. Choices from the Status Area include:  Trace Description  Time Slice  Selected Region  Filters  Selected Object Select the appropriate check box to continue. Related Information  Call Nesting Status Area Window  Dynamic Call Graph Status Area Window  Time Line Status Area Window.  Keys Help. ═══ 18.4.5. Tool Bar Cascading Choice ═══ Select the Tool bar cascading choice to have the Tool bar display or not display in your window, and to enable and disable the Hover help. The choices from the Tool bar cascaded menu are: Show Choose to either show or hide the Tool bar. Hover Choose to either enable or disable displaying the help text when the mouse pointer hovers over the Tool bar buttons. Related Information  Keys Help. ═══ 18.4.6. Settings Cascading Choice ═══ The choices from the Settings cascaded menu allow you to save current settings or return to the original settings. Save Save the current session settings. Restore initial defaults Restore the original settings. Related Information  Save Choice  Restore Initial Defaults Choice  Keys Help. ═══ 18.4.6.1. Save Choice ═══ Select the Save choice to save the current settings. These settings are stored in the ICSPERF.INI file and remain active until that file is erased. To restore the default settings, select the Restore initial defaults choice. Related Information  Restore Initial Defaults Choice  Keys Help. ═══ 18.4.6.2. Restore Initial Defaults Choice ═══ Select the Restore initial defaults choice to change to the original or default settings. You can select the Save choice to save settings. Related Information  Save Choice.  Keys Help. ═══ 18.5. Execution Density Project Menu ═══ This menu appears when you start the Performance Analyzer from within the WorkFrame environment. The Project menu gives you direct access to all of the actions that you can perform from your current location. When you select the Edit function choice from this menu, the source code for the selected function is displayed in the default editor for WorkFrame's edit action. Related Information  Search Paths Window  Trace Generation Window  Keys Help ═══ 18.5.1. Edit Function Choice ═══ Select the Edit function choice to edit a source file in WorkFrame's default editor. This choice lets you edit the source for a function selected on the Execution Density diagram. When you are working in the WorkFrame environment, this choice is available from the Project menu on the Execution Density diagram. It is also available from the Selected Item pop-up menu on the Execution Density diagram. To locate a source file for editing, the Performance Analyzer must first locate the executable containing the name of the source file. The Performance Analyzer searches the following paths (in the order listed) to locate an executable: 1. Path specified in the Locate Executable window 2. Path specified in the Search path for executable files: entry field of the Search Paths window 3. Directory where the executable was located when the trace file was created 4. The current working directory 5. Path specified by the PATH environment variable. To identify the name of the source file, the Performance Analyzer looks at the debug information in the executable. The Performance Analyzer then searches the following paths (in the order listed) to locate the source file: 1. Path specified in the Locate Source File window 2. Path specified in the Search path for source files: entry field of the Search Paths window 3. Path specified in the compile statement (if provided) 4. Directory where the executable was located when the trace file was created 5. The current working directory 6. Path specified by the INCLUDE environment variable. If, after searching these paths, the Performance Analyzer cannot find the: 1. Executable, it displays the Locate Executable window to let you enter the path where the executable resides. 2. Source file, it displays the Locate Source File window to let you enter the path where the source file resides. Once the source file for a function is located, the file is opened to the first line of the function's code. Notes 1. The Performance Analyzer remembers the paths you enter in the Locate Executable and Locate Source File windows and uses them to look for files the next time you select the Edit function choice. 2. You can specify paths that you want the Performance Analyzer to use by selecting the Search Paths choice in the Options menu on the Performance Analyzer - Window Manager window. The paths you enter are automatically saved for the current session. If you want to save the paths for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Locate Executable Window  Locate Source File Window  Search Paths Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 18.6. Execution Density Help Menu ═══ The Help menu has the following choices: Help index Displays an index of Help topics. General help Displays Help for the active window. Using help Describes how to use Help. How do I? Displays task Help. Product information Displays information about the Performance Analyzer. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 18.6.1. Help Index Choice ═══ Select the Help index choice to display an alphabetical index of Performance Analyzer Help topics. This choice is available from the Help menu of the Execution Density diagram. Use the Previous push button to return to the last topic you viewed. Use the Search... push button to locate topics in the index. Use the Print... push button to print a topic. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 18.6.2. General Help Choice ═══ Select the General help choice to display Help information for the active window. This choice is available from the Help menu of the Execution Density diagram. The online Help panel displayed is the same panel that is displayed when you place your cursor inside the window and press F1. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 18.6.3. Using Help Choice ═══ Select the Using help choice for a description of how to use the IBM Performance Analyzer Help facility. This choice is available from the Help menu of the Execution Density diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 18.6.4. How Do I? Choice ═══ Select the How do I? choice to display the Performance Analyzer task help. This choice is available from the Help menu of the Execution Density diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 18.6.5. Product Information ═══ Select the Product information choice to display copyright and version information about the Performance Analyzer application. This choice is available from the Help menu of the Execution Density diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 18.7. Execution Density Current Column Indicator ═══ An arrow called the current column indicator is displayed at the top of the columns. The current column indicator lets you move to each column. Use the mouse to move to each column. To move the current column indicator, click on the column of interest and the arrow moves. You can drag the current column indicator arrow with the mouse and the Selected object information will change. Related Information  Execution Density Status Area  Keys Help. ═══ 18.8. Execution Density Vertical Ruler ═══ The Vertical Ruler, located to the left of the diagram window, shows scale. To change the scale, select the Scale pages... choice from the View menu, and the Scale Pages window appears. Related Information  Execution Density Status Area  Keys Help. ═══ 18.9. Execution Density Status Area ═══ The Status Area, located at the top of the window, describes the settings of the diagram. You can select the Status area choice to change the appearance of the area at the top of the Execution Density window. When you select the Status area... choice,the Status Area window appears. The choices in the Status area window include: Trace description Shows the description given to the trace file. Time slice Displays the value of the time slice. Selected region Displays the start, end, and total time of a selected region. Filters Shows when selected filters, such as functions and threads, are active. Selected object Displays the name of the selected object. Related Information  Call Nesting Status Area  Dynamic Call Graph Status Area  Time Line Status Area  Keys Help. ═══ Trace Description Status Line ═══ Trace description displays the descriptive text associated with the trace file being viewed in the diagram. This description comes from information you supply in either the Create Trace window or in the Trace Generation window before the trace file is created. Related Information  Execution Density Status Area Window  Execution Density Diagram.  Keys Help. ═══ Time Slice Status Line ═══ Time slice displays the amount of time associated with the height of a single horizontal line (or pixel) in the diagram. The time slice may be changed by changing the diagram's scale. The Performance Analyzer divides the entire trace time into equal time slices. Related Information  Execution Density Status Area Window  Execution Density Diagram.  Keys Help. ═══ Selected Region Status Line ═══ Selected region displays the start, end, and total time of a selected region. You can highlight a region of the diagram to see how long it took the code to execute. To highlight, press and hold mouse button one and drag the pointer across the region of the diagram that you want to check. Release mouse button one to end the highlighting. Start time Shows the point where you started selecting End time Displays the point where you stopped. Elapsed time Shows how long the selected region took to execute. So, if you started selecting on the main function at 2.3 seconds and ended at 17.5 seconds, the Start time would be 2.3 seconds, the End time would be 17.5 seconds, and the Elapsed time would be 15.2 seconds. Related Information  Execution Density Status Area Window  Execution Density Diagram.  Keys Help. ═══ Filters Status Line ═══ Filters shows when selected filters, such as threads and functions, are active. Filters allow you to temporarily reduce the amount of trace data displayed. So when you select specific threads or functions to display, you are filtering the trace data displayed. Related Information  Include Functions Window  Include Threads Window  Execution Density Diagram  Execution Density Status Area Window.  Keys Help. ═══ Selected Object Status Line ═══ Selected object displays the name of the selected object. Use mouse button one to click on an area of the diagram to see the name of the object file. Note: In the Execution Density diagram, the current column indicator designates the selected object. Related Information  Execution Density Diagram  Execution Density Status Area Window.  Keys Help. ═══ 18.10. Execution Density Diagram Pop-up Menu ═══ The pop-up menus allow you to quickly access the most often used features. There are two pop-up menus: Diagram and Selected Item. Execution Density Diagram Pop-up Menu This pop-up menu contains most of the choices from the Edit and Options menus. To access this menu, use mouse button two to click on the background area of the diagram. The menu is displayed with the following choices:  Find Function  Find next  Zoom in  Zoom out  Scale pages  Include functions  Include threads  Color  Column width Related Information  Execution Density Selected Item Pop-up Menu  Execution Density Diagram  Keys Help. ═══ 18.11. Execution Density Selected Item Pop-up Menu ═══ Execution Density Selected Item Pop-up Menu To access this pop-up menu, highlight a region of interest, move the mouse pointer into that area, and click on mouse button two. This menu contains the following choices:  Zoom to selected range  Correlation  Edit function Related Information  Execution Density Diagram Pop-up Menu  Execution Density Diagram  Keys Help. ═══ 19. Statistics Diagram ═══ Statistics Diagram The Statistics diagram gives you a textual report of execution time by function or executable. Use this information to find hot spots in the overall program execution. The Statistics diagram has two panes: Statistics Summary Pane and Statistics Details Pane. Resizing the Window You can resize the windows horizontally and the panes vertically. To resize a window or window pane, press and drag the mouse pointer on the split bar until the windows or window panes are the size you want. Note: Times are shown in milliseconds. Areas of the Statistics Window The following topics describe the areas of the Statistics diagram:  Menu Bar Summary The choices available from the Statistics diagram menu bar are: - Trace file - View - Options - Project - Help.  the Summary pane  the Details pane Related Information  Statistics Summary Pane  Statistics Details Pane  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 19.1. Statistics Summary Pane ═══ The Summary pane is in the top area of the window. You must scroll the window panes to view all of the information. Information provided in the Summary pane is as follows:  Executable name  Trace file description Note: This will only appear if you entered a description on the Create Trace window in the Trace File Description field when you created the trace file.  Execution date  Execution time  Number of executables generating events  Number of functions generating events  Number of threads generating events  Total number of events  Total number of annotations  Number of user events  Maximum call nest depth  Number of trace buffer flushes  Total trace time excluding overhead  Trace overhead Related Information  Statistics Details Pane  Hints and Tips  Keys Help. ═══ 19.2. Statistics Details Pane ═══ The Details pane is in the bottom area of the window. You must scroll the window panes to view all of the information. The Details pane has a left and right pane. The left pane displays the fully qualified name of the component that the statistics have been gathered on. Information provided on the left side of the Details pane is as follows: When you have selected Functions from the View and Details on menus, you see:  Function  Object file  Executable When you have selected Executables from the View and Details on menus, you see:  Executable With function names, if user events have been included in the trace, they will appear as separate entries in the list of function names. The user events will be the function name that made the call to the user event, followed by the user event in parentheses. For executables, only the executable name is displayed. Information provided on the right side of the Details pane is as follows:  Percent Of Execution  Percent On Stack  Number of Calls  Execution Time  Time on Stack  Minimum Call  Maximum Call  Average Call Note: If you disabled the Time stamp events choice before you created your trace file, only the Number of Calls column will be displayed on the right side of the Details pane. Related Information  Statistics Summary Pane  Hints and Tips  Keys Help. ═══ 19.3. Statistics Trace File Menu ═══ The following choices are available from the Statistics Trace file menu: Open as Displays a new or an additional diagram. Save as text Creates a file containing the summary information. Printer settings... Allows you to choose printer settings for your output. Print Prints the textual report of the Statistics diagram. Window Manager Displays the Window Manager window. Exit Performance Analyzer Exits the Performance Analyzer and closes all windows. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Time Line Diagram  Keys Help. ═══ 19.3.1. Open As Cascading Choice ═══ Select the Open as 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 as from the Trace file menu. A cascaded menu is displayed with the following choices: Call Nesting Dynamic Call Graph Execution Density Statistics Time Line 2. Select the name of the diagram you want to view. A new window opens and displays the diagram you selected. Related Information  Selecting a Trace File to Analyze  Keys Help. ═══ 19.3.1.1. Call Nesting Choice ═══ The Call Nesting choice is available from the Open as cascaded menu. When you select Call Nesting, the Call Nesting Diagram diagram displays. Related Information  Open As Choice  Keys Help. ═══ 19.3.1.2. Dynamic Call Graph Choice ═══ The Dynamic Call Graph choice is available from the Open as cascaded menu. When you select Dynamic Call Graph, the Dynamic Call Graph displays. Related Information  Open As Choice  Keys Help. ═══ 19.3.1.3. Execution Density Choice ═══ The Execution density choice is available from the Open as cascaded menu. When you select Execution Density, the Execution Density Diagram diagram displays. Related Information  Open As Choice  Keys Help. ═══ 19.3.1.4. Statistics Choice ═══ The Statistics choice is available from the Open as cascaded menu. When you select Statistics, the Statistics Diagram displays. Related Information  Open As Choice  Keys Help. ═══ 19.3.1.5. Time Line Choice ═══ The Time Line choice is available from the Open as cascaded menu. When you select Time Line, the Time Line diagram displays. Related Information  Open As Choice  Keys Help. ═══ 19.3.2. Save As Text... Choice ═══ Select the Save as text... choice to save the Statistics diagram as an ASCII file. When you select the Save as text... choice, the Save As Text window appears. Related Information  Keys Help. ═══ 19.3.2.1. Save As Text Window ═══ The Save as Text window lets you select the file name where the Performance Analyzer will save all the text contained in the Summary and Details areas of the window into an ASCII file. Note: Save As Text does not save the binary trace file. Related Information  Keys Help. ═══ 19.3.3. Printer Settings... Choice ═══ Select the Printer settings... choice to select settings for your print jobs. When you select the Printer settings... choice, the Printer Settings window appears.  OK  Font  Job  Cancel  Help Related Information  Keys Help. ═══ 19.3.4. Print... Choice ═══ Select the Print... choice to print the information from the Statistics diagram. To print the Statistics diagram, select the Print... choice from the Trace file menu. The Print window appears. Related Information  Keys Help. ═══ 19.3.5. Window Manager Choice ═══ Select the Window manager choice to display the Window Manager window. Related Information  Performance Analyzer - Window Manager  Keys Help. ═══ 19.3.6. Exit Performance Analyzer Choice ═══ Select Exit Performance Analyzer to exit the Performance Analyzer and all windows. Related Information  Keys Help. ═══ 19.4. Statistics View Menu ═══ The choices from the View menu are: Details on Select to view the Details window by function or executable. Include threads Select which threads to include or exclude in the diagram. Sort Select how you want to sort the Details window. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Time Line Diagram  Keys Help. ═══ 19.4.1. Details On Choice ═══ Select the Details on choice to view the executables or the functions: Functions Groups details by function. Executables Groups details by executables. Related Information  Find Choice  Keys Help. ═══ 19.4.1.1. Functions Choice ═══ Select the Functions choice to view the functions included in the trace. To view the functions, select Functions from the Details on menu. A check mark displays to show the choice is selected. Related Information  Executables Choice  Keys Help. ═══ 19.4.1.2. Executables Choice ═══ Select the Executables choice to view the executables included in the trace. To view the executables, select Executables from the Details on menu. A check mark displays to show the choice is selected. Related Information  Functions Choice  Keys Help. ═══ 19.4.2. Include Threads... Choice ═══ Select the Include threads... choice to select which threads are displayed in the diagram. When you select the Include threads... choice, an Include Threads window appears. Note: The percentages are based upon the total execution time of the selected threads, not the total execution time. When you change the threads you affect the percentages. Related Information  Keys Help. ═══ 19.4.2.1. Include Threads Window ═══ Use the Include Threads window to select or isolate specific threads, and to enable and display specific pattern recognitions in the Statistics diagram. Use the mouse to highlight your thread selections. Note: The percentages are based upon the total execution time of the selected threads, not the total execution time. When you change the threads you affect the percentages. Selecting Specific Threads To select a specific thread: 1. Select the specific threads you want to display. 2. Select the appropriate push button to continue:  OK  Select all  Deselect all  Cancel  Help. Selecting All Threads To select all threads: 1. Select the Select all push button in the Include threads window to select all threads. 2. Select the appropriate push button to continue:  OK  Select all  Deselect all  Cancel  Help Related Information  Dynamic Call Graph  Execution Density Diagram  Analyze Trace Window  Keys Help. ═══ 19.4.3. Sort Cascading Choice ═══ Select the Sort choice to sort the Details windows based on one of the columns. When you select Sort, a cascaded menu is displayed with the following choices:  Function name  Object file name  Executable name  Execution time  Time on call stack  Number of calls  Minimum call  Maximum call  Average call. Related Information  Analyze Trace Window  Keys Help. ═══ 19.4.3.1. Function Name Choice ═══ Select the Function name choice to sort the names of the functions listed in the Function column in the Details window in alphabetical order. The names are placed in alphabetical order. Select the choice and the Details window sorts all data by function name. Related Information  Sort Choice  Object file name  Executable name  Execution time  Time on call stack  Number of calls  Minimum call  Maximum call  Average call.  Keys Help. ═══ 19.4.3.2. Object File Name Choice ═══ Select the Object file name choice to sort on the Object file column in the Details window in alphabetical order. Select the choice and the Details window sorts all data by object file name. Related Information  Sort Choice  Function name  Executable name  Execution time  Time on call stack  Number of calls  Minimum call  Maximum call  Average call.  Keys Help. ═══ 19.4.3.3. Executable Name Choice ═══ Select the Executable name choice to sort by the Executable column in the Details window in alphabetical order. Select the choice and the Details window sorts all data by executable name. Related Information  Sort Choice  Function name  Object file name  Execution time  Time on call stack  Number of calls  Minimum call  Maximum call  Average call.  Keys Help. ═══ 19.4.3.4. Execution Time Choice ═══ Select the Execution Time choice to sort by the Execution Time column in the Details window in ascending order based upon execution time. Select the choice and the Details window sorts all data by execution time. Each entry in this column designates the percentage of the total execution time spent in a particular function. Related Information  Sort Choice  Function name  Object file name  Executable name  Time on call stack  Number of calls  Minimum call  Maximum call  Average call.  Keys Help. ═══ 19.4.3.5. Time on Call Stack Choice ═══ Select the Time on call stack choice to sort by the Time on call stack column in the Details window in descending order. Select the choice and the Details window sorts all data by the Call stack column. The function with the most time is placed at the top of the column. Each entry in this column designates the total amount of time a particular function was on the call stack. Related Information  Sort Choice  Function name  Object file name  Executable name  Execution time  Number of calls  Minimum call  Maximum call  Average call.  Keys Help. ═══ 19.4.3.6. Number of Calls Choice ═══ Select the Number of calls choice to sort the Number of calls column in the Details window in descending order. Select the choice and the Details window sorts all data by number of calls column. Each entry in this column designates the total number of times a particular function is called. Related Information  Sort Choice  Function name  Object file name  Executable name  Execution time  Time on call stack  Minimum call  Maximum call  Average call.  Keys Help. ═══ 19.4.3.7. Minimum Call Choice ═══ Select the Minimum call choice to sort the Minimum call column in the Details window in ascending order. The function with the least number of calls is placed at the top. Select the choice and the Details window sorts all data by the minimum call time column. Each entry in this column designates the minimum time spent in a call to a particular function. Related Information  Sort Choice  Function name  Object file name  Executable name  Execution time  Time on call stack  Number of calls  Maximum call  Average call.  Keys Help. ═══ 19.4.3.8. Maximum Call Choice ═══ Select the Maximum call choice to sort the Maximum callcolumn in the Details window in descending order. The function with the most calls is placed at top. Select the choice and the Details window sorts all data by Maximum Call time column. Each entry in this column designates the average amount of time spent in calls to a particular function. Related Information  Sort Choice  Function name  Object file name  Executable name  Execution time  Time on call stack  Number of calls  Minimum call  Average call.  Keys Help. ═══ 19.4.3.9. Average Call Choice ═══ Select the Average call choice to sort the Average call column in the Details window in descending order. The function with the longest average call time is placed at the top. Select the choice and the Details window sorts all data by Average the call time column. Each entry in this column designates the average amount of time spent in calls to a particular function. Related Information  Sort Choice  Function name  Object file name  Executable name  Execution time  Time on call stack  Number of calls  Minimum call  Maximum call  Keys Help. ═══ 19.5. Statistics Options Menu ═══ The Options menu allows you to customize the Statistics diagram and display additional information. The following choices are available from the Options menu: Find Searches for a function or an executable. Font Selects the font and font size for the Summary and Details panes. Tool bar Use the Tool bar for a shortcut to other menus. Settings Saves the current settings or restores the default settings. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 19.5.1. Find... Choice ═══ Select the Find... choice to search for functions or executables in the Statistics diagram. Find Functions: When you select the Find... choice, and Functions is enabled, a Find Function window appears. Note: To enable the Functions choice, from the View menu, select Details on, then select Functions A check mark appears beside the word Functions when it is enabled. Click on it again to disable it. Find Executables: When you select the Find... choice, and Executables is enabled, a Find Executables window appears. Note: To enable the Executables choice, from the View menu, select Details on, then select Executables A check mark appears beside the word Executables when it is enabled. Click on it again to disable it. Related Information  Keys Help. ═══ Find Functions Window ═══ Use the Find Functions window to search for a specific function in the diagram. Searching for Functions To search for a function: 1. From the View menu, select Details on, then click on Functions. Note: Depending upon whether you selected Functions or Executables, the Find window comes up with the appropriate selection in the container area. 2. Leave the Find string entry field blank and press enter to get a display a list of all functions in the list box, or enter the file name (or part of the file name) of the function you want to display in the list box. Click on the Case sensitive check box to enable case sensitive searching. 3. Select a function from the list box. 4. Select the appropriate push button to continue:  OK  Cancel  Help Note: The function is highlighted when found. Related Information  Find Executables Choice  Keys Help. ═══ Find Executables Window ═══ Use the Find executables window to search for a specific executable in the diagram. Searching for Executables To search for an executable: 1. From the View menu, select Details on, then click on Executables. Note: Depending upon whether you selected Functions or Executables, the Find window comes up with the appropriate selection in the container area. 2. Leave the Find string entry field blank and press enter to get a display a list of all executables in the list box, or enter the file name (or part of the file name) of the executable you want to display in the list box. Click on the Case sensitive check box to enable case sensitive searching. 3. Select an executable from the list box. 4. Select the appropriate push button to continue:  OK  Cancel  Help Note: The executable is highlighted when found. Related Information  Find Function Choice  Keys Help. ═══ 19.5.2. Font... Choice ═══ Select the Font... choice to change the font, font style, and font size for the text area of the Statistics window. This choice is available from the Options menu of the Statistics window. When you select this choice, the Font window appears. The Font window has the following areas: Name entry field Type a font name in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a name from the list. Size entry field Type a font size in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a size from the list. Style entry field Type a font style in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a style from the list. Emphasis check boxes Click on one of these check boxes to outline, underscore, or strikeout text. Sample box This box shows a sample of how text will appear with the settings you have selected. Ok push button Changes the font according to the settings you selected. Reset push button Changes all font settings to the default settings. Cancel push button Closes the window without making changes. Related Information  Keys Help. ═══ 19.5.3. Tool Bar Cascading Choice ═══ Select the Tool bar cascading choice to have the Tool bar display or not display in your window, and to enable and disable the Hover help. The choices from the Tool bar cascaded menu are: Show Choose to either show or hide the Tool bar. Hover Choose to either enable or disable displaying the help text when the mouse pointer hovers over the Tool bar buttons. Related Information  Keys Help. ═══ 19.5.4. Settings Cascading Choice ═══ The choices from the Settings cascaded menu allow you to save current settings or switch to the original settings. Save Save the current session settings. Restore initial defaults Restore the original settings. Related Information  Save Choice  Restore Initial Defaults Choice  Keys Help. ═══ 19.5.4.1. Save Choice ═══ Select the Save choice to save the current settings. These settings are stored in the ICSPERF.INI file and remain active until that file is erased. To restore the default settings, select the Restore defaults choice. Related Information  Restore Initial Defaults Choice  Keys Help. ═══ 19.5.4.2. Restore Initial Defaults Choice ═══ Select the Restore initial defaults choice to change to the original or default settings. You can select the Save choice to save settings. Related Information  Save Choice  Keys Help. ═══ 19.6. Statistics Project Menu ═══ This menu appears when you start the Performance Analyzer from within the WorkFrame environment. The Project menu gives you direct access to all of the actions that you can perform from your current location. When you select the Edit function choice from this menu, the source code for the selected function is displayed in the default editor for WorkFrame's edit action. Related Information  Search Paths Window  Keys Help ═══ 19.6.1. Edit Function Choice ═══ Select the Edit function choice to edit a source file in WorkFrame's default editor. This choice lets you edit the source for a function selected on the Statistics diagram. When you are working in the WorkFrame environment, this choice is available from the Project menu on the Statistics diagram. It is also available from the pop-up menu on the Statistics diagram. To locate a source file for editing, the Performance Analyzer must first locate the executable containing the name of the source file. The Performance Analyzer searches the following paths (in the order listed) to locate an executable: 1. Path specified in the Locate Executable window 2. Path specified in the Search path for executable files: entry field of the Search Paths window 3. Directory where the executable was located when the trace file was created 4. The current working directory 5. Path specified by the PATH environment variable. To identify the name of the source file, the Performance Analyzer looks at the debug information in the executable. The Performance Analyzer then searches the following paths (in the order listed) to locate the source file: 1. Path specified in the Locate Source File window 2. Path specified in the Search path for source files: entry field of the Search Paths window 3. Path specified in the compile statement (if provided) 4. Directory where the executable was located when the trace file was created 5. The current working directory 6. Path specified by the INCLUDE environment variable. If, after searching these paths, the Performance Analyzer cannot find the: 1. Executable, it displays the Locate Executable window to let you enter the path where the executable resides. 2. Source file, it displays the Locate Source File window to let you enter the path where the source file resides. Once the source file for a function is located, the file is opened to the first line of the function's code. Notes 1. The Performance Analyzer remembers the paths you enter in the Locate Executable and Locate Source File windows and uses them to look for files the next time you select the Edit function choice. 2. You can specify paths that you want the Performance Analyzer to use by selecting the Search Paths choice in the Options menu on the Performance Analyzer - Window Manager window. The paths you enter are automatically saved for the current session. If you want to save the paths for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Locate Executable Window  Locate Source File Window  Search Paths Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 19.7. Statistics Help Menu ═══ The Help menu has the following choices: Help index Displays an index of Help topics. General help Displays Help for the active window. Using help Describes how to use Help. How do I? Displays task Help. Product information Displays information about the Performance Analyzer. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 19.7.1. Help Index Choice ═══ Select the Help index choice to display an alphabetical index of Performance Analyzer Help topics. This choice is available from the Help menu of the Statistics diagram. Use the Previous push button to return to the last topic you viewed. Use the Search... push button to locate topics in the index. Use the Print... push button to print a topic. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 19.7.2. General Help Choice ═══ Select the General help choice to display Help information for the active window. This choice is available from the Help menu of the Statistics diagram. The online Help panel displayed is the same panel that is displayed when you place your cursor inside the window and press F1. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 19.7.3. Using Help Choice ═══ Select the Using help choice for a description of how to use the IBM Performance Analyzer Help facility. This choice is available from the Help menu of the Statistics diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 19.7.4. How Do I? Choice ═══ Select the How do I? choice to display the Performance Analyzer task help. This choice is available from the Help menu of the Statistics diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 19.7.5. Product Information ═══ Select the Product information choice to display copyright and version information about the Performance Analyzer application. This choice is available from the Help menu of the Statistics diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 20. Time Line Diagram ═══ 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. The Time Line diagram is similar to the Call Nesting diagram, but the distance between successive events in the diagram are drawn in proportion to the actual time between the events as recorded in the trace file. The names of functions are only drawn when the time spent in that function is large enough to allow the name to be drawn. This value is dependent upon the size of the font being used. For example, with the default font, the distance between the call to the function and the next event must be at least twenty scan lines. This is done to ensure that the function name will not be overwritten by another function name or overdrawn by a line representing a function call or thread switch. You can use this diagram to find where a deadlock occurred. Access violations, system exceptions and other such program errors are recorded in the trace file as user events, as are any messages generated in the code by calls to the Performance Analyzer. These events are indicated by a black diamond in the diagram, and if there is sufficient space, the text associated will be drawn to the right of the events. Areas of the Time Line Window The following topics describe the areas of the Time Line diagram:  Menu Bar Summary The following choices are available from the Time Line diagram menu bar: - Trace File - Edit - View - Options - Project - Help.  Status Area The Status Area provides information about the following: - Trace Description - Time Slice - Selected Region  Vertical Ruler  Time Line Pop-up Menus - Time Line Diagram Pop-up Menu. - Time Line Selected Item Pop-up Menu. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram.  Hints and Tips  Keys Help. ═══ 20.1. Time Line Trace File Menu ═══ The following choices are available from the Trace file menu : Open as Shows a new or an additional diagram. Printer settings... Allows you to choose printer settings for your output. Print selected region... Prints a selected area of the diagram. Window Manager Displays the Window Manager. Exit Performance Analyzer Exits the Performance Analyzer. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Keys Help. ═══ 20.1.1. Open As Cascading Choice ═══ Select the Open as choice to view another diagram. You can open as many new diagram windows as you want. To select a new diagram: 1. Select Open as from the Trace file menu. A cascaded menu is displayed with the following choices: Call Nesting Dynamic Call Graph Execution Density Statistics Time Line 2. Select the name of the diagram you want to view. A new window opens and displays the diagram you selected. Related Information  Selecting a Trace File to Analyze  Keys Help. ═══ 20.1.1.1. Call Nesting Choice ═══ The Call Nesting choice is available from the Open as cascaded menu. When you select Call Nesting, the Call Nesting Diagram displays. Related Information  Open As Choice  Keys Help. ═══ 20.1.1.2. Dynamic Call Graph Choice ═══ The Dynamic Call Graph choice is available from the Open as cascaded menu. When you select Dynamic Call Graph, the Dynamic Call Graph displays. Related Information  Open As Choice  Keys Help. ═══ 20.1.1.3. Execution Density Choice ═══ The Execution Density choice is available from the Open as cascaded menu. When you select Execution Density, the Execution Density Diagram diagram displays. Related Information  Open As Choice  Keys Help. ═══ 20.1.1.4. Statistics Choice ═══ The Statistics choice is available from the Open as cascaded menu. When you select Statistics, the Statistics Diagram displays. Related Information  Open As Choice  Keys Help. ═══ 20.1.1.5. Time Line Choice ═══ The Time Line choice is available from the Open as cascaded menu. When you select Time Line, the Time Line diagram displays. Related Information  Open As Choice  Keys Help. ═══ 20.1.2. Printer Settings... Choice ═══ Select the Printer settings... choice to select settings for your print jobs. When you select the Printer settings... choice, the Printer Settings window appears.  OK  Font  Job  Cancel  Help Related Information  Keys Help. ═══ 20.1.3. Print Selected Region... Choice ═══ Select the Print selected region... choice to print a selected area of the Time Line diagram. To print an area of the Time Line diagram, highlight the area and then select this choice from the Trace file menu. The Print Selected Region window appears. Related Information  Keys Help. ═══ 20.1.4. Window Manager Choice ═══ Select the Window manager choice to display the Window Manager window. Related Information  Performance Analyzer - Window Manager  Keys Help. ═══ 20.1.5. Exit Performance Analyzer Choice ═══ Select Exit Performance Analyzer to exit the Performance Analyzer and close all associated windows. Related Information  Keys Help. ═══ 20.2. Time Line Edit Menu ═══ The Edit menu allows you to locate and change text in the Time Line diagram. Items you can select from this menu include the following: Find function Search for a function call or return. Find Next Find the next occurrence of the last item you searched for. Select time Go to a specific time in the diagram. Select time range Select a specified time in the diagram. Select all Select the entire Time Line diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Keys Help. ═══ 20.2.1. Find Function... Choice ═══ Select the Find function... choice to search for a function call or return. When you select the Find function... choice, the Find Function window appears. Related Information  Find Next Choice  Time Line Diagram Pop-up Menu  Keys Help. ═══ Find Function Window ═══ Use the Find function window to search for a specific function in the diagram. You can choose to search when the function was called or returned. Searching for Calls or Returns To search for a function call or return: 1. Do any of the following for the Find string entry field:  Leave the entry field blank and press enter to display a list of all functions in the list box  Enter the file name of the function that you want to display in the list box  Enter the first few characters of the function file name that you want to display in the list box  Enter an asterisk (*) and part or all of the function file name that you want to display in the list box. Note: This is useful when you are searching for a C++ de-mangled function that has class information in front of the function name. Click on the Case sensitive check box to enable case sensitive searching. 2. Select a function from the list box. For Call Nesting, Execution Density and Time Line Diagrams:  Choose to search for when the function was called or returned.  Select the Call radio button to find when a function was called. OR  Select the Return radio button to find when a function returned. 3. Select the appropriate push button to continue:  OK  Cancel  Help Note: The function is highlighted when found. Related Information  Find Next Choice  Keys Help. ═══ 20.2.2. Find Next Choice ═══ Select the Find Next choice to locate the next instance of the searched text. To find the next occurrence, select Find next from the Edit menu. The string is highlighted when found. A message box appears if the string cannot be found. Related Information  Find Window  Time Line Diagram Pop-up Menu  Keys Help. ═══ 20.2.3. Select Time... Choice ═══ Select the Select time... choice to go to a specific time in the diagram. When you select the Select time... choice, the Select Time window appears. Related Information  Select Time Range Window  Keys Help. ═══ 20.2.3.1. Select Time Window ═══ Use the Select Time window to go to a specific time in the diagram. Going to a Specific Time To select the time: 1. Select the appropriate radio button:  seconds (s)  milliseconds (ms)  microseconds (us) 2. Use the spin buttons to select the time you want to display. 3. Select the appropriate push button to continue:  OK  Cancel  Help. Related Information  Select Time Range Window  Call Nesting Diagram  Execution Density Diagram  Time Line Diagram.  Keys Help. ═══ 20.2.4. Select Time Range... Choice ═══ Select the Select time range... choice to choose a specific period of time to view. When you select the Select time range... choice, the Select Time Range window appears. Related Information  Select Time Window  Keys Help. ═══ Select Time Range Window ═══ Use the Select Time Range window to view a specific period of time. Selecting Time Periods To select the time period: 1. In the Start time list box, use the spin buttons to select the start time you want to highlight. 2. To select the time, select the appropriate radio button:  seconds (s),  milliseconds (ms),  microseconds (us). 3. In the End time list box, use the spin buttons to select the end time, where the highlight will stop. 4. To select the time, select the appropriate radio button:  seconds (s),  milliseconds (ms),  microseconds (us). 5. Select the appropriate push button to continue:  OK  Cancel  Help. Related Information  Select Time Window  Call Nesting Diagram  Execution Density Diagram  Time Line Diagram  Analyze Trace Window  Keys Help. ═══ 20.2.5. Select All Choice ═══ Select the Select all choice to highlight the entire diagram. To remove the highlighting, select a specific function. Related Information  Select Time Window  Select Time Range Window  Keys Help. ═══ 20.3. Time Line View Menu ═══ The choices available from the View menu are: Zoom in Magnifies a region of interest in the diagram. Zoom out Reduces the diagram to starting size. Zoom to selected range Magnify the diagram to focus on the highlighted area. Scale pages Selects the size of the diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Keys Help. ═══ 20.3.1. Zoom In Choice ═══ Select the Zoom In choice to magnify the Time Line diagram. Selecting the Zoom In choice will magnify the Time Line diagram by a factor of 5. The point in the trace file at the top of the current page will remain fixed, resulting in the view changing to show the top one fifth of the previously displayed page. If the diagram is already scaled to its maximum, this choice will be disabled. If the diagram is scaled within a factor of 5 of the maximum magnification, this choice will bring the diagram to its full magnification. The Zoom In choice is offered in both the View menu and the Time Line Diagram Pop-up Menu Also, holding the Ctrl key and pressing the + key will perform the same function. Related Information  Zoom Out Choice  Zoom to Selected Range Choice  Time Line Selected Item Pop-up Menu  Keys Help. ═══ 20.3.2. Zoom Out Choice ═══ Select the Zoom Out choice to reduce the magnification of the Time Line diagram. Selecting the Zoom Out choice will decrease the magnification of the Execution Density diagram by a factor of 5. The point in the trace file at the top of the current page will remain fixed, resulting in the view changing to display the previously displayed page in the top one fifth of the new view. If necessary, the diagram will adjust to ensure that time past the end of the trace file is not displayed. If the diagram is already scaled to its minimum magnification, this choice will be disabled. If the diagram is scaled within a factor of 5 of the minimum magnification, this choice will bring the diagram to a full 100 % view. The Zoom Out choice is offered in both the View menu and the Time Line Diagram Pop-up Menu Also, holding the Ctrl key and pressing the - key will perform the same function. Related Information  Zoom In Choice  Zoom to Selected Range Choice  Time Line Diagram Pop-up Menu  Keys Help. ═══ 20.3.3. Zoom to Selected Range Choice ═══ Select the Zoom to selected range to magnify an area of interest in the Time Line diagram. To magnify a region of interest, highlight the region using the mouse or the Select time range... choice and select Zoom to selected range from the View menu. The scale of the diagram will be expanded so that the highlighted area fills the entire display. Note: When the magnification is at its maximum, the choice will be disabled. Also, if it is impossible to magnify the diagram to the degree required to stretch the highlighted region across the entire diagram, the highest possible magnification will be used. Shortcut Method After highlighting the area of interest, use mouse button two to click on the highlighted area. From the displayed Time Line Selected Item Pop-up Menu, choose Zoom to selected region. Related Information  Zoom In Choice  Zoom Out Choice  Time Line Selected Item Pop-up Menu  Keys Help. ═══ 20.3.4. Scale Pages... Choice ═══ Use the Scale pages... 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 the Scale pages... choice, a Scale Pages window appears. Related Information  Time Line Diagram Pop-up Menu  Restore Initial Defaults Choice  Keys Help. ═══ 20.4. Time Line Options Menu ═══ The Options menu allows you to customize the Time Line diagram and display additional information. The following choices are available from the Options menu: Call Stack Shows all functions on the call stack at a selected point. Correlation Synchronizes other diagrams to display the same highlighted region. Font Selects the font, font style, and font size for the diagram. Thread layout Selects the indentation amount for each thread column and whether to draw separator bars between threads. Status area Controls the gray area at the top of the window. Tool bar Use the Tool bar for a shortcut to other menus. Settings Saves the current settings or restores the defaults. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram Pop-up Menu  Time Line Selected Item Pop-up Menu  Keys Help. ═══ 20.4.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 the Call Stack... choice, the Call Stack window appears. Related Information  Time Line Selected Item Pop-up Menu  Restore Initial Defaults Choice  Keys Help. ═══ Call Stack Window ═══ Select the Call Stack window to display the order in which the functions were called at a selected point. Displaying the Call Stack To display a call stack for a function: 1. Click on a function to select it. 2. Select Call Stack from the Options menu. A Call Stack window appears the function you selected and its parents (called functions) in the order in which they were called. 3. Select the appropriate push button to continue:  OK  Help. Related Information  Call Nesting Diagram  Time Line Diagram.  Keys Help. ═══ 20.4.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. When you select the Correlate... choice, the Correlation window appears. Related Information  Time Line Selected Item Pop-up Menu  Keys Help. ═══ 20.4.3. Font... Choice ═══ Select the Font... choice to change the font, font style, and font size for the text area of the Time Line window. This choice is available from the Options menu of the Time Line window. When you select this choice, the Font window appears. The Font window has the following areas: Name entry field Type a font name in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a name from the list. Size entry field Type a font size in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a size from the list. Style entry field Type a font style in this entry field or click on the scroll bar on the right side of the entry field to see a list of choices and select a style from the list. Emphasis check boxes Click on one of these check boxes to outline, underscore, or strikeout text. Sample box This box shows a sample of how text will appear with the settings you have selected. Ok push button Changes the font according to the settings you selected. Reset push button Changes all font settings to the default settings. Cancel push button Closes the window without making changes. Related Information  Time Line Diagram Pop-up Menu  Keys Help. ═══ 20.4.4. 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 window appears. Related Information  Time Line Diagram Pop-up Menu  Keys Help. ═══ Thread Layout Window ═══ Use the Thread Layout window to control the thread indentation and to control whether separator bars are drawn between the threads. Controlling Indentation and Separator Bars To use the Thread Layout window: 1. Select the spin buttons in the Indents per thread entry field until the value you want displays. The maximum indentation value is 20 pixels. 2. Select the check box to draw separator lines between the threads. A check mark symbol in the box indicates to draw separator bars and an empty box indicates not to draw the separator bars. 3. Select the appropriate push button to continue:  Set  Apply  Cancel  Help. Related Information  Call Nesting Diagram  Time Line Diagram  Keys Help. ═══ 20.4.5. Status Area... Choice ═══ Select the Status area... choice to control the area at the top of the window. When you select the Status area... choice, the Status Area window appears. Related Information  Keys Help. ═══ 20.4.5.1. Status Area Window ═══ Use the Status Area window to control the area at the top of the window. The check boxes represent the choices in the Status Area that you can show or hide. When you disable the check box the choice is hidden. Likewise, when you enable the check box the choice displays in the Status Area. In each diagram the Status Area displays different information. When you select the Status Area window, the choices in the window change based upon the Status Area of the diagram. Choices from the Status Area include:  Trace Description  Time Slice  Selected Region Select the appropriate check box to continue. Related Information  Call Nesting Status Area Window  Execution Density Status Area Window  Dynamic Call Graph Status Area Window  Keys Help. ═══ 20.4.6. Tool Bar Cascading Choice ═══ Select the Tool bar cascading choice to have the Tool bar display or not display in your window, and to enable and disable the Hover help. The choices from the Tool bar cascaded menu are: Show Choose to either show or hide the Tool bar. Hover Choose to either enable or disable displaying the help text when the mouse pointer hovers over the Tool bar buttons. Related Information  Keys Help. ═══ 20.4.7. Settings Cascading Choice ═══ The choices from the Settings cascaded menu allow you to save current settings or switch to the original settings. Save Save the current session settings. Restore Initial Defaults Choice Restore the original settings. Related Information  Save Choice  Restore Initial Defaults Choice  Keys Help. ═══ 20.4.7.1. Save Choice ═══ Select the Save choice to save the current settings. These settings are stored in the ICSPERF.INI file and remain active until that file is erased. To restore the default settings, select the Restore initial defaults choice. Related Information  Restore Initial Defaults Choice  Keys Help. ═══ 20.4.7.2. Restore Initial Defaults Choice ═══ Select the Restore initial defaults choice to change to the original or default settings. You can select the Save choice to save settings. Related Information  Save Choice  Keys Help. ═══ 20.5. Time Line Project Menu ═══ This menu appears when you start the Performance Analyzer from within the WorkFrame environment. The Project menu gives you direct access to all of the actions that you can perform from your current location. When you select the Edit function choice from this menu, the source code for the selected function is displayed in the default editor for WorkFrame's edit action. Related Information  Search Paths Window  Trace Generation Window  Keys Help ═══ 20.5.1. Edit Function Choice ═══ Select the Edit function choice to edit a source file in WorkFrame's default editor. This choice lets you edit the source for a function selected on the Time Line diagram. When you are working in the WorkFrame environment, this choice is available from the Project menu on the Time Line diagram. It is also available from the Selected Item pop-up menu on the Time Line diagram. To locate a source file for editing, the Performance Analyzer must first locate the executable containing the name of the source file. The Performance Analyzer searches the following paths (in the order listed) to locate an executable: 1. Path specified in the Locate Executable window 2. Path specified in the Search path for executable files: entry field of the Search Paths window 3. Directory where the executable was located when the trace file was created 4. The current working directory 5. Path specified by the PATH environment variable. To identify the name of the source file, the Performance Analyzer looks at the debug information in the executable. The Performance Analyzer then searches the following paths (in the order listed) to locate the source file: 1. Path specified in the Locate Source File window 2. Path specified in the Search path for source files: entry field of the Search Paths window 3. Path specified in the compile statement (if provided) 4. Directory where the executable was located when the trace file was created 5. The current working directory 6. Path specified by the INCLUDE environment variable. If, after searching these paths, the Performance Analyzer cannot find the: 1. Executable, it displays the Locate Executable window to let you enter the path where the executable resides. 2. Source file, it displays the Locate Source File window to let you enter the path where the source file resides. Once the source file for a function is located, the file is opened to the first line of the function's code. Notes 1. The Performance Analyzer remembers the paths you enter in the Locate Executable and Locate Source File windows and uses them to look for files the next time you select the Edit function choice. 2. You can specify paths that you want the Performance Analyzer to use by selecting the Search Paths choice in the Options menu on the Performance Analyzer - Window Manager window. The paths you enter are automatically saved for the current session. If you want to save the paths for subsequent sessions, select the Options menu and then select the Save choice from the Settings cascaded menu. Related Information  Locate Executable Window  Locate Source File Window  Search Paths Window  Starting the Performance Analyzer from WorkFrame  Keys Help. ═══ 20.6. Time Line Help Menu ═══ The Help menu has the following choices: Help index Displays an index of Help topics. General help Displays Help for the active window. Using help Describes how to use Help. How do I? Displays task Help. Product information Displays information about the Performance Analyzer. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 20.6.1. Help Index Choice ═══ Select the Help index choice to display an alphabetical index of Performance Analyzer Help topics. This choice is available from the Help menu of the Time Line diagram. Use the Previous push button to return to the last topic you viewed. Use the Search... push button to locate topics in the index. Use the Print... push button to print a topic. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 20.6.2. General Help Choice ═══ Select the General help choice to display Help information for the active window. This choice is available from the Help menu of the Time Line diagram. The online Help panel displayed is the same panel that is displayed when you place your cursor inside the window and press F1. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 20.6.3. Using Help Choice ═══ Select the Using help choice for a description of how to use the IBM Performance Analyzer Help facility. This choice is available from the Help menu of the Time Line diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 20.6.4. How Do I? Choice ═══ Select the How do I? choice to display the Performance Analyzer task help. This choice is available from the Help menu of the Time Line diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 20.6.5. Product Information ═══ Select the Product information choice to display copyright and version information about the Performance Analyzer application. This choice is available from the Help menu of the Time Line diagram. Related Information  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Hints and Tips  Keys Help. ═══ 20.7. Time Line Status Area ═══ The Status Area, located at the top of the window, describes the settings of the diagram. You can select the Status area choice to change the appearance of the area at the top of the Time Line window. When you select the Status area... choice,the Status Area window appears. The choices in the Status area window include: Trace description Shows the description given to the trace file. Time slice Displays the value of the time slice. Selected region Displays the start, end, and total time of a selected region. Related Information  Call Nesting Status Area  Execution Density Status Area  Dynamic Call Graph Status Area  Execution Density Status Area  Keys Help. ═══ 20.8. Time Line Vertical Ruler ═══ The Vertical Ruler, located to the left of the diagram window, shows scale. To change the scale, select the Scale pages... choice from the View menu, and the Scale Pages window appears. Related Information  Keys Help. ═══ 20.9. Time Line Diagram Pop-up Menu ═══ The pop-up menus allow you to quickly access the most often used features. There are two pop-up menus: Diagram and Selected Item. This pop-up menu contains almost all the choices from the Edit and Options menus. To access this menu, use mouse button two to click on the background area of the diagram. The menu is displayed with the following choices:  Find function  Find next  Zoom in  Zoom out  Scale pages  Font  Thread layout Related Information  Time Line Selected Item Pop-up Menu  Keys Help. ═══ 20.10. Time Line Selected Item Pop-up Menu ═══ To access this pop-up menu, highlight a region of interest, move the mouse pointer into that area, and click on mouse button two. This menu contains the following choices:  Zoom to selected range  Call Stack  Correlation  Edit function Related Information  Time Line Diagram Pop-up Menu  Keys Help. ═══ 21. System Exceptions ═══ Certain system exceptions generated by your program will be logged in the trace file as user events. The system exceptions that are logged as user events are:  XCPT_ACCESS_VIOLATION  XCPT_ILLEGAL_INSTRUCTION  XCPT_INTEGER_DIVIDE_BY_ZERO  XCPT_INTEGER_OVERFLOW  XCPT_PRIVILEGED_INSTRUCTION  XCPT_FLOAT_DENORMAL_OPERAND  XCPT_FLOAT_DIVIDE_BY_ZERO  XCPT_FLOAT_INEXACT_RESULT  XCPT_FLOAT_INVALID_OPERATION  XCPT_FLOAT_OVERFLOW  XCPT_FLOAT_STACK_CHECK  XCPT_FLOAT_UNDERFLOW  XCPT_UNABLE_TO_GROW_STACK  XCPT_SIGNAL  XCPT_GUARD_PAGE_VIOLATION These system exceptions appear in the Call Nesting, Time Line, and Statistics diagrams. In the Call Nesting diagram, you can search for system exceptions user events. In the Call Nesting and Time Line diagrams, system exceptions appear as follows: System Exception: Guard page violation Related Information  Find User Event Window  Call Nesting  Statistics  Time Line diagrams.  Trace Generation Window  Keys Help. ═══ 22. Hints for Using the Performance Analyzer ═══ The Performance Execution Trace Analyzer helps you understand the behavior of your program by collecting execution trace data and presenting it in several diagrams. The following hints can help you take advantage of some of the Performance Analyzer's features:  Hint 1: Reduce the amount of trace data the Performance Analyzer collects.  Hint 2: Use Performance Analyzer features to customize your trace file.  Hint 3: Use a combination of diagrams to understand your program.  Hint 4: Use correlation to see different aspects of a point of interest.  Hint 5: Use the Dynamic Call Graph's color and size characteristics.  Hint 6: Use the Execution Density diagram to see trends.  Hint 7: Use the zoom function to see details.  Hint 8: Find patterns of calls and returns.  Hint 9: Place annotations in your trace files.  Hint 10: Use the diagrams to help you understand exception exits. ═══ 22.1. Hint 1: Reduce the amount of trace data the Performance Analyzer collects. ═══ By default, the Performance Analyzer generates event information for every function possible. However, this sometimes causes the trace file to become very large. Besides using a large amount of disk space, the Performance Analyzer may take an unacceptable amount of time to create a diagram from the trace file and, once created, the diagram may be difficult to manage. The following topics describe several ways you can limit the size of your trace file:  Creating a Customized Trace File  Enabling and Disabling Components  Selecting the Call Depth for Each Thread  Using Time Stamps  Tracing File Accesses  Setting and Removing Triggers  Starting and Stopping the Performance Analyzer from Your Program  Trace On Push Button  Trace Off Push Button ═══ 22.2. Hint 2: Use Performance Analyzer features to customize your trace file. ═══  Add user events to your program before you trace it. User events are calls to a Performance Analyzer defined function. You pass it a character string, and that character string is inserted into your trace file. You can view the string in the Call Nesting, Statistics, and Time Line diagrams. Since the Performance Analyzer time stamps user events, they appear in the Time Line diagram at the time they occurred in the execution. Be sure to use static, constant character strings for your user event strings. If you add a user event to your program source file, you must also include a prototype for the PERF entry point. For C and C++ programs, the prototype will be inserted for you when you compile your program if you place the following statement at the beginning of your source file: #include Note: If you want to insert the prototype yourself, the prototypes for C and C++ programs are as follows: C Prototype VOID PERF (PSZ string); C++ Prototype EXTERN "C" {VOID PERF(PSZ string);} Add a call to the entry point everywhere you want a user event generated. A sample user event that could be placed in your program is: PERF ("well, we actually got to this code"); The Performance Analyzer time stamps the entrance and exit of each function. If you want to get better time resolution for a large function for example, you can divide the function into smaller functions during performance measurements, or you can add user events. User events enable you to subdivide large functions into higher resolution time slices. For more information and examples, see Creating User Events in Your Program.  The CPPOPA3.OBJ file contains entry points called PerfStart and PerfStop that accept calls from the program you are tracing. Calls to the PerfStart and PerfStop entry points cause the Performance Analyzer to start and stop tracing, respectively. By putting these calls into your source code, you can control precisely when the Performance Analyzer starts and stops gathering event during program execution. For more information and examples, see Starting and Stopping the Performance Analyzer from Your Program.  Use the Annotate... choice in the Call Nesting diagram to insert notes and reminders into your trace file after it is created. You can place annotations next to any event you select in the diagram. For more information, see Annotate... Choice.  You can select the File access choice from the Options menu to trace common access calls that your program makes. By determining when and where file access calls occur and identifying the files they access, you can better understand how your program is behaving. For more information, see Tracing System Calls.  You can also trace APIs by linking to the Performance Analyzer's traceable versions of the DOS, PM WIN, and PM GPI libraries: _DOSCALL.LIB, _PMWIN.LIB, and _PMGPI.LIB, respectively. For more information, see Tracing System Calls. ═══ 22.3. Hint 3: Use a combination of diagrams to understand your program. ═══ Sometimes two or more diagrams can help you understand a program better. For instance, if you have a new program to learn, and you don't want to wade through code listings to determine how the code works, you can use the Dynamic Call Graph and the Call Nesting and Time Line diagrams to get a good understanding of the program's flow. The Call Nesting diagram shows the order in which functions are called and returned. The times for these events are displayed in the Time Line diagram. The Dynamic Call Graph shows all of the program's threads, the relative importance (in execution time) of the different functions, and the call hierarchy. For a description of each of the Performance Analyzer diagrams, see Analyzing a Trace File. ═══ 22.4. Hint 4: Use correlation to see different aspects of a point of interest. ═══ Correlation is helpful because one diagram cannot show everything of interest within a trace file. Additionally, some events are easier to find in one diagram, but the information in another is more meaningful; therefore, you can locate the event in one diagram and correlate to another. For these and other instances, the Performance Analyzer provides three time-scaled diagrams that can be correlated: Call Nesting, Execution Density, and Time Line. You can correlate these diagrams based on a specific time or event, or on a range of time or events. For example, use the Call Nesting diagram to identify the order and names of functions called, and then use the Time Line diagram to find out how long a function took to execute. Or you can use the Execution Density diagram to see general patterns that lead up to a certain point, and then correlate that point to the Call Nesting diagram to see the exact order of the function calls. For instructions on correlating diagrams, see Correlation Window. ═══ 22.5. Hint 5: Use the Dynamic Call Graph's color and size characteristics. ═══ The Dynamic Call Graph shows you information associated with calls and functions. In this diagram, a node represents a function and an arc, which is displayed between a pair of nodes, represents a call from one function to another. Double-click on any node to display a window that provides both the name of the represented function and execution information. Double-click on any arc to display a window that provides the caller and callee of the arc. Node and Arc Color Node color is based on the execution time spent in a function; arc color is based on the number of calls between pairs of functions. For nodes: white is used for functions with no execution time; gray is used for functions with execution times less than 1/8 of the maximum execution time; blue is used for functions with execution times between 1/8 and 1/4 of the maximum; yellow is used for functions with execution times between 1/4 and 1/2 of the maximum; and red is used for functions with execution times greater than 1/2 of the maximum. For arcs: white shows that no calls were made between the functions; gray shows that less than 1/8 of the maximum number of calls made were made between the functions; blue shows that 1/8 to 1/4 of the maximum number of calls made were made between the functions; yellow shows that 1/4 to 1/2 of the maximum number of calls made were made between the functions; and red shows that at least 1/2 of maximum number of calls made were made between the functions. Green shows that a node or an arc is selected. Node Size Node size represents both execution time and active time. The height of each node is determined by its execution time relative to the function that has the greatest execution time. The width of each node is determined by its active time relative to the function that has the greatest active time. Active time is the time spent on the call stack. If a function is waiting for a message, the time spent waiting is logged as active time. A node representing a main function that doesn't do much processing on its own would be short and wide because it spends little time executing, but remains on the call stack for a long time. Conversely, a node representing a function that does not call any other functions (a leaf node) would be at least as tall as it is wide (maybe taller) because it is executing whenever it is on the call stack. For more information, see Dynamic Call Graph and Arcs and Nodes. ═══ 22.6. Hint 6: Use the Execution Density diagram to see trends. ═══ Trends can help you identify areas that execute well and areas that need more attention. The Execution Density diagram is similar to the Time Line diagram in that time is proportional along the vertical axis. The trace time is divided into a series of equal time slices. The Performance Analyzer assigns every function traced a vertical column in the diagram. If a particular function is executed during a time slice, the Performance Analyzer displays color in its column. Think of these time slices as buckets that will hold a certain capacity of time. The Performance Analyzer walks through the trace file filling up each bucket in sequence. When a bucket becomes full, the Performance Analyzer examines its contents and calculates the percentage of the time slice that each function accumulated. Then, the Performance Analyzer maps the percentages to a range, and from there to a color, which is displayed on your screen. (Both the ranges and the colors can be varied by selecting the Color choice in the diagram's Options menu.) The colors help you quickly identify functions that use the most time and those that use the least. When you alter the scale of the diagram, you actually change the buckets' capacity. When filling, each bucket's contents will differ, and the diagram will look different. An event that previously filled a small part of a large bucket might now fill a large part of several smaller buckets. The Execution Density diagram has filtering capabilities that make it easier to see trends. One way to filter out some of the functions is to set their colors equal to the background color. For example, if you don't want to see functions that take 0 to 1 percent of the execution time during a given time slice, set the color for that range to the background color and those functions will not be displayed. For more information, see Execution Density Diagram. ═══ 22.7. Hint 7: Use the zoom function to see details. ═══ A useful technique for zooming in to the Execution Density and Time Line diagrams is using the zoom and correlation functions together. Zooming sometimes forces the highlighted region off the page; however, correlation can help you quickly find it again. To use this technique: 1. Open your trace file in a diagram that has both zoom and correlation capabilities (Execution Density or Time Line). 2. Open another diagram that allows correlation (Call Nesting, Execution Density, or Time Line). 3. Highlight the area that you want to enlarge (that is, zoom in on) in the first diagram. 4. Correlate the first diagram to the second. 5. In the first diagram, select the Zoom in choice from the View menu as many times as you want. 6. Correlate the second diagram to the first. The region you originally highlighted is back in view. Note: If you zoom in too far, you can select the Zoom out choice to quickly go back one step. For more information, see Zoom In Choice, Zoom Out Choice, and Correlation Window. If you don't want to open another diagram, follow these steps to use the zoom function: 1. Highlight the area that you want to enlarge. 2. Select the Zoom in choice, and then scroll until you see the area you highlighted. 3. Continue alternately selecting Zoom in and scrolling to the highlighted area until the diagram is enlarged to the degree you desire. Note: If you zoom in too far, you can select the Zoom out choice to quickly go back one step. For more information, see Zoom In Choice and Zoom Out Choice. Not only does the Zoom to selected range choice provide a quick way to zoom in on an area of interest, it also provides an easy way to restore the diagram to full scale after it's been reduced. To restore the diagram to full scale: 1. Select the Select all choice in the View menu. 2. Select the Zoom to selected range choice in the Options menu. For more information, see Zoom In Choice, Zoom Out Choice, and Zoom To Selected Range Choice. ═══ 22.8. Hint 8: Find patterns of calls and returns. ═══ The Call Nesting diagram's Pattern Recognition feature identifies patterns of calls and returns on a single thread. When this feature is on, the Call Nesting diagram identifies these patterns with a curved arc. The number of consecutive repetitions of each pattern is displayed next to the arc. Grouping repeated patterns shortens the number of pages needed to display the trace file. An experienced user seeing many repetitions of patterns could improve performance by grouping functions with pragma alloc_text statements, thereby limiting the number of page swaps between calls in the pattern. For more information, see Include Threads... Choice. ═══ 22.9. Hint 9: Place annotations in your trace files. ═══  An annotation is a way of placing a bookmark or reminder in the trace file after it has been created. In the Call Nesting diagram, you can use the Annotate... choice to insert notes and reminders next to any function you select.  You also can make notes to yourself in the trace file with user events. User events are placed in the code before you create the trace file to mark where certain structures are executed or to help you locate specific areas in the trace file during analysis. Consider a user event to be a smart "print" statement that can be used for a variety of debugging purposes. For more information on inserting annotations and customizing a trace file, see Annotate... choice and Hint 2: Use Performance Analyzer features to customize your trace file. ═══ 22.10. Hint 10: Use the diagrams to help you understand exception exits. ═══ Because the Performance Analyzer is constantly recording events, you not only have a record of where exception exits occur, you also have a record of when they occur. For example, when your program causes an exception, you can open your trace file in the: Call Nesting diagram... to find the function in which the exit occurred, what happened before it reached that point, and where any unexpected thread switches may have occurred. Dynamic Call Graph... to find the call hierarchy and how many functions executed prior to the exit. Execution Density diagram... to find trends of activity and abnormal behavior, such as a function taking longer than it should. Statistics diagram... to find cumulative information about function execution times and numbers of calls. Time Line diagram... to find each function's execution time and when each call and return was made. For more information, see Analyzing a Trace File. For more information on specific features and techniques, see other Performance Analyzer online help topics or the user's guide that came with your software. ═══ 22.11. Limitations of the Performance Analyzer ═══ Note the following when using the Performance Analyzer:  If you have written customized setjmp or longjmp functions to replace the C Set ++ library versions, the Performance Analyzer will not function correctly.  A user event can be created as a constant character string or can be specified as an area into which a character string has been built. After the application has terminated, the Performance Analyzer accesses the data area of the target application so that the user events can be written to disk. Therefore, each user event must occupy a unique storage location.  The Performance Analyzer's timing counter wraps after approximately one hour. If you attempt to collect events more than one hour after you first start collecting events, the time stamps will not be accurate.  The Performance Analyzer cannot accurately determine when thread switches occur. Because of this, the call stack may not be accurate near thread switches. In the Execution Density and Time Line diagrams, the time after a thread switch is associated with the function on the top of the call stack of the switched-out thread. If there is no such function, the time is not associated with any function, causing gaps to appear in the diagrams.  If you minimize the Trace Generation window, the window of the target application remains in its original state.  If you minimize the Overview window in the Dynamic Call Graph, it does not appear in the OS/2 Window List.  File access calls are not traced for I/O flush operations that occur after the target application has finished. They are not included in the function-called counts for those file accesses.  The Performance Analyzer can trace and analyze applications generated by the IBM C Set ++ compiler. You cannot use the Performance Analyzer to trace files produced by other 16-bit or 32-bit compilers. The Performance Analyzer can trace only the first 64 threads in your program.  The Performance Analyzer cannot generate or analyze trace data for child processes in a multiprocess application.  Tracing applications that are currently being debugged by IPMD.EXE or analyzed by the Performance Analyzer in another session can cause unpredictable results.  The Performance Analyzer cannot calculate operating system overhead. Be aware that running other applications in the background while running the Performance Analyzer will impact your execution times.  C++ applications often have functions that consist of a small number of instructions. On fast machines, these function call times are small compared to the system clock resolution of 838 nanoseconds. As a result, reported overall execution times may be imprecise, especially when these small functions are called thousands of times. For information on Performance Analyzer features, see other online help topics or the user's guide that came with your software. ═══ 23. Keys Help ═══ Ctrl+H On the Trace Generation window and each of the diagrams, you can display Help information for many functions by highlighting the function and pressing Ctrl+H. This Help information is available for functions such as IBM Open Class functions, OS/2 system functions, and C runtime functions. Performance Analyzer - Window Manager Window The following are shortcut keys for the File menu. Choice Shortcut Keys Exit Performance Analyzer F3 Trace Generation Window The following are shortcut keys for the Program menu. Choice Shortcut Keys Window manager Ctrl+W Exit Performance Analyzer F3 Call Nesting Diagram The following are shortcut keys for the Trace file menu. Choice Shortcut Keys Window manager Ctrl+W Exit Performance Analyzer F3 The following are shortcut keys for the Edit menu. Choice Shortcut Keys Find next Ctrl+N Annotate... Ctrl+A The following are shortcut keys for the Find... cascaded menu. Choice Shortcut Keys Function... Ctrl+F Dynamic Call Graph The following are shortcut keys for the Trace file menu. Choice Shortcut Keys Window manager Ctrl+W Exit Performance Analyzer F3 The following are shortcut keys for the View menu. Choice Shortcut Keys Zoom in Ctrl++ Zoom out Ctrl+- The following are shortcut keys for the Options menu. Choice Shortcut Keys Find function... Ctrl+F Execution Density Diagram The following are shortcut keys for the Trace file menu. Choice Shortcut Keys Window manager Ctrl+W Exit Performance Analyzer F3 The following are shortcut keys for the Edit menu. Choice Shortcut Keys Find function... Ctrl+F Find next Ctrl+N The following are shortcut keys for the View menu. Choice Shortcut Keys Zoom in Ctrl++ Zoom out Ctrl+- Statistics Diagram The following are shortcut keys for the Trace file menu. Choice Shortcut Keys Window manager Ctrl+W Exit Performance Analyzer F3 The following are shortcut keys for the Options menu. Choice Shortcut Keys Find... Ctrl+F Time Line Diagram The following are shortcut keys for the Trace file menu. Choice Shortcut Keys Window manager Ctrl+W Exit Performance Analyzer F3 The following are shortcut keys for the Edit menu. Choice Shortcut Keys Find function... Ctrl+F Find next Ctrl+N The following are shortcut keys for the View menu. Choice Shortcut Keys Zoom in Ctrl++ Zoom out Ctrl+- ═══ Add/Change Push Button ═══ Select the Add/Change push button to add or change the comments you have added in the Annotation dialog window of the Call Nesting diagram. ═══ Analyze Trace... Push Button ═══ Select the Analyze Trace... push button to quickly access the Analyze Trace window from which you can select Performance Analyzer diagrams to analyze a trace file. ═══ Apply Push Button ═══ Select the Apply push button to use the selected settings in the current window without making them permanent. ═══ Cancel Push Button ═══ Select the Cancel push button to exit the current window without saving any changes. ═══ Deselect All Push Button ═══ Select the Deselect all push button to deselect all selected elements in the window. This push button is available from the Correlation, Include Functions, and Include threads windows. ═══ Create Trace... Push Button ═══ Select the Create Trace... push button to quickly access the Create Trace window from which you can start creating a trace file. ═══ Find Caller Push Button ═══ Select the Find Caller push button in the Who Calls Whom window to select and center the node that makes the call. For more information, see the Who Calls Whom window. ═══ Find Callee Push Button ═══ Select the Find Callee push button in the Who Calls Whom window to select and center the node that is called. For more information, see the Who Calls Whom window. ═══ Find Push Button ═══ Select the Find push button in the Find 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 Find Function window. ═══ Find Push Button ═══ Click on the Find push button to display the Find File window, which helps you locate a file that you want to trace or analyze. ═══ Font Push Button ═══ Select the Font push button in the Printer Settings window to select from available fonts. ═══ Job Properties Push Button ═══ Select the Job properties push button in the Printer Settings window for more detailed information about your print job. From the Job properties... window, select the appropriate push buttons and check boxes. ═══ Help Push Button ═══ Select the Help push button to learn how to use the window that is currently displayed. ═══ OK Push Button ═══ Select the OK push button to save the changes and close the window. ═══ Remove Push Button ═══ Select the Remove push button to remove a comment from the Annotate dialog window in the Call Nesting diagram. ═══ Reset Push Button ═══ Select the Reset push button to return to the default font settings. ═══ Set Push Button ═══ Select the Set push button to accept the changes in the current window. ═══ Select All Push Button ═══ Select the Select all push button to select all elements in the window. ═══ Stop Push Button ═══ Select the Stop push button in the Application Monitor window to stop your program while it is being analyzed by the Performance Analyzer. When you stop the application, you also stop the collection of trace data. The Analyze Trace window is displayed after the trace stops so that you can select one or more diagrams in which to view the trace data. Related Information  Trace Off Push Button.  Trace On Push Button.  Analyze Trace Window  Selecting a Trace File to Analyze. ═══ Trace Push Button ═══ Select a program you want to trace, and then click on the Trace push button to close the Trace Generation window and begin tracing your program. ═══ Trace Off Push Button ═══ Select the Trace off push button in the Application Monitor window to stop tracing events in your program. Trace off does not cause your program to stop running; it stops trace events from being recorded to the trace file. When the Application Monitor window is displayed, the Performance Analyzer has already started tracing events, so you can select Trace off anytime after the window is displayed. Note: Return events are still logged for functions that were called before you turned trace off, and execution time will still be logged against functions that were called but have not returned to the caller. You can also turn tracing off from your program by calling the Performance Analyzer function PerfStop. To turn tracing back on, call the Performance Analyzer function PerfStart. The calls to PerfStart and PerfStop can be anywhere in your program, even in different functions, object modules, or DLLs. If the trace is already off, Calling PerfStop has no effect. If the trace is already on, Calling PerfStart has no effect. For instructions, see Starting and Stopping the Performance Analyzer from Your Program. Related Information  Trace On Push Button.  Selecting a Trace File to Analyze. ═══ Trace On Push Button ═══ Select the Trace on push button in the Application Monitor window to start tracing events in your program. Trace on does not cause your program to start running; it causes trace events to start being recorded to the trace file. When the Application Monitor window is displayed, the Performance Analyzer has already started tracing events, so you cannot select Trace on until you have first selected Trace off. You can also turn tracing on from your program by calling the Performance Analyzer function PerfStart. To turn tracing off, call the Performance Analyzer function PerfStop. The calls to PerfStart and PerfStop can be anywhere in your program, even in different functions, object modules, or DLLs. If the trace is already on, Calling PerfStart has no effect. If the trace is already off, Calling PerfStop has no effect. For instructions, see Starting and Stopping the Performance Analyzer from Your Program. Related Information  Trace Off Push Button  Selecting a Trace File to Analyze. ═══ Who Calls Whom Push Button ═══ Select the Who calls whom push button in the Function Information window to display only the selected node and the nodes that called the selected node. For more information, see the Function Information window. ═══ Whom Do I Call Push Button ═══ Select the Whom do I call push button in the Function Information window to display only the selected node and the nodes that the selected node called. For more information, see the Function Information window. ═══ 23.1. Glossary ═══ Double-click on any term to see its definition:  Active Time  Annotation  Arc  Buffer Wrapping  Buffer Wrap  Call  Call Nesting Diagram  Component  Correlation  Disabling Components  Dos calls  Dynamic Call Graph  Enabling Components  Events  Executable File  Execution Density Diagram  File Access  Flush  function  Hot Spots  Microseconds (us)  Milliseconds (ms)  Minus Icon  Node  Object Files  Overhead  Pixels  Profile Hooks  Plus Icon  Return  Run Time  Scaling  Statistics  Seconds (s)  Shortcut Keys  Thread  Tic  Time Line Diagram  Time Stamp  Trace Analysis  Trace file  Trigger  User Event ═══ ═══ Trademark of International Business Machines Corporation. ═══ ═══ The Performance Analyzer determines the time slice by dividing the total trace time into equal units. For instance, a 10-second trace file would have 10 time slices equal to 1 second each. The time slice value can change based on the page size in the Execution Density diagram or Time Line diagram. Each page represents an overall diagram or 100% view, there is one page. As you magnify the diagram, the number of pages increase and the time slice value increases. ═══ ═══ Active time is the total time a function is on the call stack while its thread is executing. The time is displayed in the Statistics diagram and Dynamic Call Graph ═══ ═══ An annotation is a descriptive comment or an explanatory note that you can add to the Call Nesting diagram. Annotations are a way to place a bookmark in the trace file. You can add notes to the diagram about what is being displayed next to the calls and returns. The Performance Analyzer writes these comments in the trace file, so you can display the comments anytime you look at the trace file in the future. ═══ ═══ An arc is a directed line connecting two nodes in the Dynamic Call Graph. It shows the relationship between the two nodes. ═══ ═══ 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. ═══ ═══ 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. ═══ ═══ 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. ═══ ═══ The Call Nesting diagram shows the program 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. ═══ ═══ A component can be an executable file, an object, or a function from your program. ═══ ═══ 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. ═══ ═══ When you disable an executable, object file, or function, the Performance Analyzer does not include information about that component in the trace file. You can disable a component for one trace analysis to tailor the data in the trace file. ═══ ═══ Dos calls are calls made to the operating system through functions with names beginning with a Dos prefix, such as, DosExit and DosOpen. ═══ ═══ The Dynamic Call Graph shows a graphical view of the target program's execution. Each function called is displayed as a node. Calls are shown as arcs between nodes. The colors and sizes of nodes and arcs show the amount of time spent in the function and the number of calls between functions. ═══ ═══ When you enable an executable, object file, or function, the Performance Analyzer includes information about that component in the trace file. You can enable a component for one trace analysis to tailor the data in the trace file. ═══ ═══ An environment variable is a variable associated with a given process and is inherited from its parent process. For example, PATH. ═══ ═══ An event occurs anytime a function is called or returns. The Performance Analyzer records all events in the trace file. ═══ ═══ An executable is a file of compressed images of a program that includes each of the program segments, such as code, data, and call stack and control records that tell the loader how to tie all of the program segments together. ═══ ═══ 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. The Performance Analyzer 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. ═══ ═══ File access occurs when a given file is opened, read, written, or closed in a program. ═══ ═══ 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. The Performance Analyzer processes the contents of the virtual logging buffer and the events are written to the trace file. After the buffer is flushed, the Performance Analyzer resumes tracing the program. ═══ ═══ A function is defined by the Performance Analyzer to be a callable section within the program. For the Performance Analyzer, procedures and subroutines are synonyms of functions. ═══ ═══ Hot spots are areas within a program where a disproportionate amount of time was spent. The Performance Analyzer traces how long a function ran, which helps determine which functions caused the hot spots. ═══ ═══ Causes the time to display in microseconds. ═══ ═══ Causes the time to display in milliseconds. ═══ ═══ 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. ═══ ═══ A node is the representation of an individual function or executable in the Dynamic Call Graph. ═══ ═══ Object files are compiler output files that are linked to comprise an executable. ═══ ═══ Overhead is the time it takes to log events in the trace file. The Performance Analyzer measures its overhead and adjusts the timing information accordingly. ═══ ═══ Pixels are picture elements of a display area. ═══ ═══ When a profile hook is specified, the compiler generates a call to a profiling hook function as the first instruction in the prologue of each function. There are two profiling hook functions: _Profile_Hook32 Profile hook for all 32-bit functions. _ProfileHook16 Profile hook for all 16-bit callback functions. These functions are defined with either the _Far16 _Cdecl, or _Far16 _Pascal linkage keywords. For more information about profile hooks, see the Programming Guide. ═══ ═══ The plus icon is displayed beside an executable and object file in the Trace Generation window when the file can be shown or expanded. ═══ ═══ A return is a language construct within a function designating the end of the execution sequence in the function. ═══ ═══ Run time is the time during which a program is being executed. ═══ ═══ 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. ═══ ═══ The Statistics Diagram provides a textual report of execution time by function. It also provides summary information. ═══ ═══ Causes the time to display in seconds. ═══ ═══ 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 keyboard shortcuts for most of the menu choices in the Performance Analyzer. For a list of shortcut keys, select any of the following:  Call Nesting Diagram  Dynamic Call Graph  Execution Density Diagram  Statistics Diagram  Time Line Diagram  Trace Generation Window ═══ ═══ A thread is the basic unit of execution. A thread gives a program its context, including registers, call stack, and processor mode. Multiple threads can be running at the same time, and any particular thread can start another thread. ═══ ═══ A tic is the smallest unit of time measured by the Performance Analyzer counter. A tic measures approximately 838 nanoseconds. ═══ ═══ 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. ═══ ═══ A time stamp is the actual time at which an event occurred when the program was being traced. The Performance Analyzer time stamps when your program calls and returns from a function. ═══ ═══ A trace analysis is a record of events obtained during the execution of a program. It contains the sequences and timing of the events during program execution. ═══ ═══ A trace file is a file that contains a chronological sequence of records describing events which occurred during the program execution. The trace file contains the trace analysis information from your program. This file can be displayed by the diagrams. ═══ ═══ 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. ═══ ═══ A user event is a call to the Performance Analyzer, defined by the user, in the program. The Performance Analyzer inserts text strings into the diagrams given by the parameter supplied by this call. User events can help you diagnose problem areas in your program. ═══ ═══ The word program as used in this online help generally refers to the executable file you are tracing; and the word application as used in this online help generally refers to the Performance Analyzer. Other use of the words program and application may be used synonymously. ═══ ═══ A trace event is either a call to a function or a return from a function. ═══ ═══ The maximum number of calls made is the number of calls made between the two functions that contained the greatest number of calls between them. ═══ ═══ The maximum execution time is the amount of time required to execute the function that has the greatest execution time.