OS/2 Shareware BBS: 10 Tools

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / VSCPPv4.zip / VACPP / IBMCPP / HELP / CPPPAHDI.INF (.txt) < prev next >

Wrap

OS/2 Help File | 1995-04-12 | 38KB | 1,141 lines

ΓòÉΓòÉΓòÉ <hidden> About this Information ΓòÉΓòÉΓòÉ The How Do I... information provides solutions to common tasks that you would perform with the various components of VisualAge C++. Before you begin to use this information, it would be helpful to understand how to navigate through it: Use the Contents and Index facilities to locate topics. Use the Search facility to search the text of this document. Use hypertext links to acquire related information on the current topic. Hypertext links appear in a different color (which you can customize using the OS/2 Scheme Palette). For example, below there are two lists of hypertext links. By double-clicking on the text of the link or by pressing Enter on a highlighted link, you will open a panel of related information. To shift the focus to other links using the keyboard, use the Tab key. For more information on using this help facility, see: How to Use the Contents How to Obtain Additional Information How to Access and Use IPF Facilities For more information, see: Other Information You Might Find Helpful Communicating Your Comments to IBM Notices Trademarks ΓòÉΓòÉΓòÉ <hidden> How to Use the Contents ΓòÉΓòÉΓòÉ The Contents window is the first to appear. Some topics have a plus ( ) icon beside them. This icon indicates that additional topics are available. To expand the Contents if you are using a mouse, click on the plus ( ) icon. If you are using the keyboard, use the Up or Down Arrow key to highlight the topic, and press the plus (+) key. To see additional topics for a heading with a plus ( ) icon, click on the icon or highlight that topic and press the plus (+) key. To view a topic, double-click on the topic (or press the Up or Down Arrow key to highlight the topic, and then press the Enter key). ΓòÉΓòÉΓòÉ <hidden> How to Obtain Additional Information ΓòÉΓòÉΓòÉ After you select a topic, the information for that topic appears in a window. Highlighted words or phrases indicate that additional information is available. Certain words and phrases are highlighted in a different color from the surrounding text. These are called hypertext terms. If you are using a mouse, double-click on the highlighted word. If you are using a keyboard, press the Tab key to move to the highlighted word, and then press the Enter key. Additional information then appears in a window. ΓòÉΓòÉΓòÉ <hidden> How to Access and Use IPF Facilities ΓòÉΓòÉΓòÉ Several choices are available for managing the information presented in this document. There are three PullDown menus: the Services menu, the Options menu, and the Help menu. The actions that are selectable from the Services menu operate on the active window currently displayed on the screen. These actions include the following: Placing Bookmarks You can set a placeholder so you can retrieve information of interest to you. Searching for Information You can find occurrences of a word or phrase in the current topic, selected topics, or all topics. Printing Information You can print one or more topics. You can also print a set of topics by first marking the topics in the Contents list. Copying Information to a File You can copy a topic that you are viewing to the System Clipboard or to a file that you can edit. This method is particularly useful for copying syntax definitions and program samples into the application that you are developing. Using the actions that are selectable from the Options menu, you can change the way your Contents list is displayed. To expand the Contents and show all levels for all topics, choose Expand all from the Options PullDown menu. You can also press the Ctrl, Shift and * keys together. The actions that are selectable from the Help menu allow you to select different types of help information. For information about any of the menu choices, highlight the choice in the menu and press F1. ΓòÉΓòÉΓòÉ <hidden> Placing Bookmarks ΓòÉΓòÉΓòÉ When you place a bookmark on a topic, it is added to a list of bookmarks you have previously set. You can view the list, and you can remove one or all bookmarks from the list. If you have not set any bookmarks, the list is empty. To set a bookmark, do the following: 1. Select a topic from the Contents. 2. When that topic appears, select the Bookmark option from the Services menu. 3. If you want to change the name used for the bookmark, type the new name in the field. 4. Click on the Place radio button (or press the Up or Down Arrow key to select it). 5. Click on OK (or select it and press Enter). The bookmark is then added to the bookmark list. ΓòÉΓòÉΓòÉ <hidden> Searching for Information ΓòÉΓòÉΓòÉ You can specify a word or phrase to be searched. You can also limit the search to a set of topics by first marking the topics in the Contents list. To search for a word or phrase in all topics, do the following: 1. Select the Search option from the Services menu. 2. Type the word or words to be searched for. 3. Click on All sections (or press the Up or Down Arrow keys to select it). 4. Click on Search (or select it and press Enter) to begin the search. 5. The list of topics where the word or phrase appears is displayed. ΓòÉΓòÉΓòÉ <hidden> Printing Information ΓòÉΓòÉΓòÉ You can print one or more topics, the index, or the table of contents. Make sure that your printer is connected to the serial port, configured correctly, and ready for input. To print: 1. Select Print from the Services menu. 2. Select what you want to print. Note that the This section and Marked sections choices are only available if you are viewing a topic or if you have marked topics, respectively. To mark topics in the table of contents, press the Ctrl key and click on the topics, or use the arrow keys. 3. Select Print to print what you've chosen on your printer. ΓòÉΓòÉΓòÉ <hidden> Copying Information to a File ΓòÉΓòÉΓòÉ You can copy a topic that you are viewing in two ways: Copy copies the topic that you are viewing into the System Clipboard. If you are using a Presentation Manager (PM) editor (for example, the Enhanced Editor) that copies or cuts (or both) to the System Clipboard, and pastes to the System Clipboard, you can easily add the copied information to your program source module. Copy to file copies the topic that you are viewing into a temporary file named TEXT.TMP. You can later edit that file by using any editor. TEXT.TMP is placed in the directory where your viewable document resides. To copy a topic, do the following: 1. Expand the Contents list and select a topic. 2. When the topic appears, select Copy to file from the Services menu. 3. The system puts the text pertaining to that topic into the temporary file TEXT.TMP. ΓòÉΓòÉΓòÉ <hidden> Other Information You Might Find Helpful ΓòÉΓòÉΓòÉ The VisualAge C++ provides a number of online guides and references that we hope you'll find helpful as you develop applications. This information includes: User's Guide information provides conceptual and usage information, Reference information is organized for quick access, and How Do I... information gives you specific instructions for performing common tasks. You can get to this online information from the Information folder inside the main product folder. You can also get to it from the Help menu in any of the components of the product. ΓòÉΓòÉΓòÉ <hidden> Communicating Your Comments to IBM ΓòÉΓòÉΓòÉ If there is something you like, or dislike, about this document, please let us know. You can use one of the methods listed below to send your comments to IBM. Please be sure to include the complete title of the publication that you are commenting on. For example, you would refer to the How Do I... information for the Browser as: VisualAge C++ Browser: How Do I... for OS/2. The comments you send should only pertain to the information in this document and its presentation. To request additional publications or to ask questions or make comments about the functions of IBM products or systems, you should talk to your IBM representative or your authorized IBM remarketer. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you. You can send your comments to IBM in the following ways: By mail to the following address: IBM Canada Ltd. Laboratory Information Development 2G/345/1150/TOR 1150 EGLINTON AVENUE EAST NORTH YORK, ONTARIO CANADA M3C 1H7 By FAX to the following number: - United States and Canada: (416) 448-6161 - Other countries (+1) 416-448-6161 By electronic mail to one of the following IDs. Be sure to include your entire network address if you wish to get a reply. - Internet: torrcf@vnet.ibm.com - IBMLink: toribm(torrcf) - IBM/PROFS: torolab4(torrcf) - IBMMAIL: ibmmail(caibmwt9) ΓòÉΓòÉΓòÉ <hidden> Notices ΓòÉΓòÉΓòÉ Copyright International Business Machines Corporation, 1995. All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. This edition applies to Version 3.0 of IBM VisualAge C++ for OS/2 (30H1664, 30H1665, 30H1666) and to all subsequent releases and modifications until otherwise indicated in new editions. Make sure you are using the correct edition for the level of the product. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; any such changes will be reported in subsequent revisions. Requests for publications and for technical information about IBM products should be made to your IBM Authorized Dealer or your IBM Marketing Representative. When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any ways it believes appropriate without incurring any obligation to you. Any reference to an IBM licensed program in this publication is not intended to state or imply that only IBM's licensed program may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing. IBM Corporation, 500 Columbus Avenue, Thornwood, NY, 10594, USA. This publication contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. ΓòÉΓòÉΓòÉ <hidden> Trademarks and Service Marks ΓòÉΓòÉΓòÉ The following terms used in this publication are trademarks or service marks of IBM Corporation in the United States or other countries: C/2 C Set/2 C Set ++ Common User Access CUA IBM Operating System/2 OS/2 Personal System/2 Presentation Manager PS/2 VisualAge WorkFrame/2 Other company, product, and service names, which may be denoted by a double asterisk(**), may be trademarks or service marks of others. ΓòÉΓòÉΓòÉ 1. Compile and link my 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. To compile and link your program: 1. Compile your program with the /Gh and /Ti options. 2. Link your program with the CPPOPA3.OBJ object file using the /DE option. 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 italicized. Compile: icc /c /Ti /Gh sample.c Link: icc /b"/DE" /FeSAMPLE.EXE sample.obj cppopa3.obj ΓòÉΓòÉΓòÉ 2. Trace system calls? ΓòÉΓòÉΓòÉ To trace system calls, you must specify the following libraries before OS/2 libraries: _DOSCALL.LIB _PMWIN.LIB _PMGPI.LIB 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 italicized. Compile: icc /c /Ti /Gh sample.c Link: icc /b"/DE" /FeSAMPLE.EXE sample.obj cppopa3.obj _doscall.lib _pmwin.lib _pmgpi.lib ΓòÉΓòÉΓòÉ 3. Start the Performance Analyzer? ΓòÉΓòÉΓòÉ Starting from an OS/2 Prompt The command you enter to start the Performance 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. 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 switch is optional. myprog Represents an executable file name. This is required when the /go option is specified. 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 From the Performance Analyzer - Window Manager window, you can start tracing an executable or analyzing an existing trace file. This window appears when you do either of the following: Double-click on the Performance Analyzer icon in the Tools folder. Enter the following command: icsperf Starting 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 IBM WorkFrame: Introduction. 2. Compile and link your source with the proper options. If you need help, see How do I... Compile and link my program? 3. Open a project folder in the WorkFrame window. 4. Highlight an object that represents an EXE file or a TRC file. 5. Click mouse button two on the highlighted object to display a pop-up menu. 6. Select Analyze. ΓòÉΓòÉΓòÉ 4. Limit the amount of data collected in the trace file? ΓòÉΓòÉΓòÉ There are several ways to limit the amount of data collected in your trace file. Before you compile and link your program, you can do any of the following to limit the amount of data collected: Compile only code you plan to trace with the /Gh and /Ti compile options. Place calls to the PerfStart and PerfStop entry points in your program to precisely control tracing. After a call to PerfStop is made, events are not recorded in the trace file until a call to PerfStart is made. For instructions on adding these calls, see How do I... Start and stop tracing under program control? You can do any of the following from the Trace Generation window to limit the amount of data collected. If you need help displaying the Trace Generation window, see How do I... Create a trace file? Disable program components. (Disabled components are not traced.) To do this: Double-click on a component file name or the icon next to it. 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. Decrease the call depth setting. To do this: 1. Select the Call Depth... choice from the Options menu. The Call Depth window appears. 2. Select the number of calls you want to trace or specify threads you want to include or exclude from the trace file. The default is to have all threads selected with the maximum depth of 128. You can limit the amount of data collected by selecting smaller values in the Call Depth window. Set a trigger on one or more functions. A trigger turns tracing on when a selected function is called and off when the function returns program control to the caller. If you set a trigger, the Performance Analyzer will not trace events until a triggered function is called. This is an easy way to limit the trace file data to a single function. Note: If you do not set any triggers, trace information will be collected for all traceable functions that you have not disabled. If you do set one or more triggers, trace information will only be collected for those functions on which a trigger has been set. To set a trigger: 1. Select a function on which you want to set a trigger. 2. Select the Set trigger choice in the Edit menu. The letter T appears in the icon next to the function name. Note: You can set multiple triggers. Disable time stamp recording. To do this, select the Time stamp events choice from the Options menu. The check mark next to the choice is removed to show that it is not enabled. Disabling time stamp recording does not restrict the number of events collected in the trace file. Rather, it makes generated trace files smaller because time stamps are not stored. Enable buffer wrapping. By choosing this option, your trace file will only be as large as your buffer. The buffer is reused over and over again and previously collected information is potentially destroyed. This option is useful when you are only interested in what was happening when your program ended. To do this: 1. Select the Buffer control... choice from the Options menu. The Buffer Control window appears. 2. Select the Yes radio button in the Buffer wrapping group box. ΓòÉΓòÉΓòÉ 5. Trace file accesses? ΓòÉΓòÉΓòÉ To trace file accesses, do the following: 1. Compile your program with the /Gh and /Ti options. 2. Link your program with the CPPOPA3.OBJ and _DOSCALL.LIB files. When linking your program, use the /DE option. 3. Start the analyzer from an OS/2 prompt by entering: icsperf myprog parms Where: myprog Represents an executable file name. parms Represents executable parameters. These are optional. 4. When the Trace Generation window appears, select the File access choice from the Options menu. A check mark appears next to the choice to indicate that it is enabled. 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. 5. Click on the Trace push button to create a trace file. If you need help continuing, see How do I... Create a trace file? or How do I... View a trace file in any of the five diagrams? ΓòÉΓòÉΓòÉ 6. Start and stop tracing under program control? ΓòÉΓòÉΓòÉ Place the PerfStart and PerfStop calls into your source code to control precisely when the Performance Analyzer starts and stops recording events during program execution. To turn tracing: Off, call the PerfStop entry point. On, call the PerfStart entry point. Notes: The default setting for tracing is enabled. If the trace is already on, calling PerfStart has no effect. If the trace is already off, calling PerfStop has no effect. 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 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 <icsperf.h> 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 calls to the PerfStart and PerfStop entry points 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 ΓòÉΓòÉΓòÉ 7. Create a trace file? ΓòÉΓòÉΓòÉ To create a trace file, do the following: 1. Compile and link your program with the proper options, if you have not already done so. If you need help, see How do I... Compile and link my program? 2. Start the Performance Analyzer, if you have not already done so. If you need help, see How do I... Start the Performance Analyzer? 3. From the Trace Generation window, click on the Trace push button. Notes: If you did not start the Performance Analyzer with any options, or if the Performance Analyzer is already started, you can display the Trace Generation window by doing the following: a. Click on the Create Trace... push button on the Performance Analyzer - Window Manager window. b. Fill in the appropriate entry fields when the Create Trace window appears. c. Click on OK. If you want to create a smaller trace file, there are some steps you can complete from this window that will reduce the amount of data collected. For instructions, see How do I... Limit the amount of data collected in the trace file? The Application Monitor window appears and your program begins executing. 4. Click on the Stop push button if you do not want to trace your entire program or if you suspect your program is in a loop or has deadlocked. Otherwise, wait until your program has finished executing and the Analyze Trace window appears. Once created, your trace file is stored and can be reused in different Performance Analyzer sessions without having to retrace your program. ΓòÉΓòÉΓòÉ 8. View a trace file in any of the five diagrams? ΓòÉΓòÉΓòÉ The Performance Analyzer provides the following five diagrams in which you can view and analyze a trace file: Call Nesting Dynamic Call Graph Execution Density Statistics Time Line Before you can view your program's execution in one of the diagrams, a trace file must have been created. Once created, this trace file is stored and can be reused in different Performance Analyzer sessions without having to retrace your program. To view a trace file in any of the five diagrams, do the following: 1. Create a trace file. If you need help, see How do I... Create a trace file? 2. From the Performance Analyzer - Window Manager window, display the Analyze Trace window by either clicking on the Analyze Trace... push button or selecting the Analyze trace... choice from the File menu. 3. Make sure the name of the trace file is properly entered on the Analyze Trace window. If you have just created a trace file, the Analyze Trace window is displayed with the trace file name filled in for you. 4. Select the appropriate check box or check boxes in the Analyze Trace window. 5. Click on the OK push button. ΓòÉΓòÉΓòÉ 9. Interpret the Call Nesting diagram? ΓòÉΓòÉΓòÉ If you need help opening a trace file in the Call Nesting diagram, see How do I... View a trace file in any of the five diagrams? The Call Nesting diagram shows the trace file as a sequential series of function calls and returns. This diagram helps in diagnosing problems with critical sections, sequencing protocols, thread delays, program deadlocks, and program crashes. Scroll through the diagram to: Identify which functions were called. See the order in which functions are called and returned. See the interactions among various threads. A horizontal dotted line indicates that your program has switched from one thread to another. Threads are separated in the diagram by light gray vertical lines. Get a better understanding of the program's flow. ΓòÉΓòÉΓòÉ 10. Interpret the Dynamic Call Graph? ΓòÉΓòÉΓòÉ If you need help opening a trace file in the Dynamic Call Graph, see How do I... View a trace file in any of the five diagrams? The Dynamic Call Graph is a graphical representation of your program's execution, which gives you an overall view of your program and its flow. It shows the relative importance (in terms of execution time) of the different functions and the call hierarchy. In this diagram, nodes represent functions; arcs, which are displayed between pairs of nodes, represent calls from one function to another. Double-click on any node to display a window that provides both the name of the represented function and its execution information. Double-click on any arc to display a window that provides the caller and callee of the arc. Using color and node size, this diagram helps you easily see where time is spent in the program. 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. Node size represents both execution time and active time. Node Color 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. Arc Color 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 the maximum number of calls made were made between the functions. Green shows that a node or an arc is selected. Node Size 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 generally be at least as tall as it is wide (maybe taller) because it is executing whenever it is on the call stack. ΓòÉΓòÉΓòÉ 11. Interpret the Execution Density diagram? ΓòÉΓòÉΓòÉ If you need help opening a trace file in the Execution Density diagram, see How do I... View a trace file in any of the five diagrams? The Execution Density diagram shows the program in terms of execution time. The Performance Analyzer assigns every traced function a vertical column in the diagram. Time is represented linearly along the vertical axis with time zero at the top of the diagram and the elapsed time from program startup to program termination at the bottom of the diagram. Short horizontal lines of various colors are drawn in the vertical columns. Each horizontal line in the Execution Density diagram represents a unit of time which is called a time slice. For each time slice, the Performance Analyzer calculates the percentage of time a particular function was executing during that time slice. The percentage is then mapped to a color and a short horizontal line of the appropriate color is drawn in the column representing the given function at the vertical location corresponding to the time slice. Note: Both the percentage ranges and the colors can be varied by selecting the Color choice from the diagram's Options menu. When you alter the scale of a diagram, you actually change the time slice. This could cause the colors of the short horizontal lines in the diagram to change. The Execution Density diagram is most useful when the scale is compressed because it allows you to get an overview of what functions were the most active at various stages of your program's execution. If you expand the scale too much, the time slice will be quite small. Every function will then appear to occupy a large percentage of the execution time for any given time slice. Functions might appear as long, vertical, red bars. ΓòÉΓòÉΓòÉ 12. Interpret the Statistics diagram? ΓòÉΓòÉΓòÉ If you need help opening a trace file in the Statistics diagram, see How do I... View a trace file in any of the five diagrams? The Statistics diagram is a textual report of cumulative information about your program's execution. This diagram provides: Summary information regarding the number of executables generating events, the number of functions generating events, the number of threads generating events, and the total number of events. Detailed information for each function traced, including: - Percent of total program execution time spent in the function - Percent of the total program execution time that the function was on the call stack. - Number of times the function was called. - Cumulative program execution time spent in the function. - Cumulative program execution time that the function was on the call stack. - Execution time for the shortest call to the function. - Execution time for the longest call to the function. - Average execution time for a call to the function. All of this summary information can be either printed or saved to a file on your disk. You can use the Statistics diagram to: Quickly determine which functions are consuming the largest amount of execution time. These functions are likely to be ones for which Performance Tuning would be most beneficial. Perform algorithm analysis. - By comparing the number of calls that were actually made to a particular function with the number of calls that you expected to be made, you may be able to isolate some inefficiencies in your algorithm. - By comparing the statistics for each of two different versions of an algorithm, you can determine which algorithm performs better. To do this: 1. Create a trace file for each algorithm. If you need help, see How do I... Create a trace file? 2. Open each trace file in the Statistics diagram. If you need help, see How do I... View a trace file in any of the five diagrams? Comparing the two trace files side by side will show you which algorithm is faster and by how much. Determine which of your functions are good candidates for inlining. If a function has a small average execution time and is called often, it is a good candidate for inlining. ΓòÉΓòÉΓòÉ 13. Interpret the Time Line diagram? ΓòÉΓòÉΓòÉ If you need help opening a trace file in the Time Line diagram, see How do I... View a trace file in any of the five diagrams? The Time Line diagram is like the Call Nesting diagram, but it also displays time information. It places function calls and returns in sequence along a vertical time line. Rather than a constant distance between events, as in the Call Nesting diagram, the distance between events in the Time Line diagram is determined by the time between events. In the Time Line diagram, a function call is represented by a short horizontal line to the right while a function return is represented by a short horizontal line to the left. These horizontal lines are connected by vertical lines. The length of any given vertical line is proportional to the amount of time which elapsed between the events. The Time Line diagram also shows when the flow of program execution switches from one thread to another. Thread switches are represented in the Time Line diagram as dashed horizontal lines. Threads are separated in the diagram by light gray vertical lines. The Time Line diagram can be used to: Easily locate thread switches (especially when the scale is compressed). Quickly see which functions are consuming the greatest amount of execution time. If a function consumes more processing time than you expected, you may want to take a closer look at that function to determine what you can do to improve its performance. Measure the length of a function call by doing the following: 1. Select the Edit menu. 2. Select the Find function... choice. 3. Enter the name of the function in the Find string: entry field. The Performance Analyzer finds the function, highlights it, and displays its execution information in the Status Area. ΓòÉΓòÉΓòÉ 14. Filter trace events from the diagrams? ΓòÉΓòÉΓòÉ Trace information can be filtered from the following diagrams: Call Nesting Dynamic Call Graph Execution Density Statistics From the Call Nesting and Execution Density diagrams, you can filter events by function or by thread. From the Dynamic Call Graph and Statistics diagrams, you can only filter events by thread. To filter events by function: 1. Create a trace file. If you need help, see How do I... Create a trace file? 2. Open the trace file in the Call Nesting or Execution Density diagram. If you need help, see How do I... View a trace file in any of the five diagrams? 3. Select the Include functions... choice from the View menu. 4. From the Include Functions window, deselect the functions you do not want displayed. 5. Click on the OK push button. To filter events by thread: 1. Create a trace file. If you need help, see How do I... Create a trace file? 2. Open the trace file in the Call Nesting, Dynamic Call Graph, Execution Density, or Statistics diagram. If you need help, see How do I... View a trace file in any of the five diagrams? 3. Select the Include threads... choice from the View menu. 4. From the Include Threads window, select the thread for which you want trace information displayed. 5. Click on the OK push button. ΓòÉΓòÉΓòÉ 15. Correlate events between diagrams? ΓòÉΓòÉΓòÉ Correlating events between diagrams allows you to select events in one diagram and see the same events in another diagram. The Performance Analyzer provides three time-scaled diagrams that can be correlated: Call Nesting, Execution Density, and Time Line. To correlate events between diagrams, do the following: 1. Create a trace file. If you need help, see How do I... Create a trace file? 2. Open the trace file in the Call Nesting, Execution Density, and Time Line diagrams. If you need help, see How do I... View a trace file in any of the five diagrams? 3. Highlight the area between the events of interest in any one of the open 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 the Correlation... choice from the Options menu in the highlighted diagram. 5. Click on the Select all push button in the Correlation window, and then click on the OK Since all three diagrams are time-based, there is a time associated with both the first and last events in your highlighted area. After correlating with the other diagrams, the events corresponding to this same time range are highlighted in each of the diagrams. ΓòÉΓòÉΓòÉ 16. View thread interactions in a multithreaded program? ΓòÉΓòÉΓòÉ To view thread interactions in a multithreaded program, do the following: 1. Create a trace file. If you need help, see How do I... Create a trace file? 2. Open the trace file in the Call Nesting or Time Line diagram. If you need help, see How do I... View a trace file in any of the five diagrams? 3. Scroll through the diagram using the vertical scroll bar. A horizontal dotted line indicates that your program has switched from one thread to another. This allows you to see the flow of program execution across threads and may be helpful in identifying timing problems and program deadlocks. ΓòÉΓòÉΓòÉ 17. Determine the elapsed time between two events? ΓòÉΓòÉΓòÉ To see the elapsed time between two events, do the following: 1. Create a trace file. If you need help, see How do I... Create a trace file? 2. Open the trace file in the Time Line diagram. If you need help, see How do I... View a trace file in any of the five diagrams? 3. Highlight the area between the two events in the Time Line diagram. 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 second event. c. Release the mouse button. 4. Check the Status area of the Time Line diagram for the elapsed time between events. Elapsed time is displayed at the end of the Selected region: line. ΓòÉΓòÉΓòÉ 18. Determine which functions in my program should be inlined? ΓòÉΓòÉΓòÉ To determine which functions in your program are good candidates for inlining: 1. Create a trace file. If you need help, see How do I... Create a trace file? 2. Open the trace file in the Statistics diagram. If you need help, see How do I... View a Trace file in any of the five diagrams? 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. 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. ΓòÉΓòÉΓòÉ 19. Find infinite loops and deadlocks in my program? ΓòÉΓòÉΓòÉ To find suspected infinite loops or deadlocks in your program, do the following: 1. Create a trace file. If you need help, see How do I... Create a trace file? 2. Open the trace file in the Call Nesting diagram. If you need help, see How do I... View a Trace file in any of the five diagrams? 3. Scroll to the bottom of the Call Nesting diagram. If an infinite loop or deadlock exists, the last function called is the one that contains the problem. ΓòÉΓòÉΓòÉ 20. Exit 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Application Programming Interface ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Trademark of International Business Machines Corporation. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The maximum execution time is the amount of time required to execute the function that has the greatest execution time.