Power GUI Programming with VisualAge C++

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

/ Power GUI Programming with VisualAge C++ / powergui.iso / trialva / ibmcppw / help / cppwpa3.hlp (.txt) < prev next >

Wrap

OS/2 Help File | 1996-02-22 | 344.9 KB | 12,679 lines

ΓòÉΓòÉΓòÉ 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: o IBM o VisualAge o WorkFrame Win32, Windows NT, and Windows 95 are trademarks of Microsoft Corporation. ΓòÉΓòÉΓòÉ 2. Introducing the Performance Execution Trace Analyzer ΓòÉΓòÉΓòÉ The IBM VisualAge for C++ for Windows, Version 3.5 Performance Execution Trace Analyzer is an application that helps you understand and improve the behavior of 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 executed, 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 o Preparing Your Program for the Performance Analyzer o Starting the Performance Analyzer from a Command Line. o Starting the Performance Analyzer from WorkFrame o Creating a Trace File. ΓòÉΓòÉΓòÉ 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: o Tracing Dynamic Link Libraries (DLLs) o Tracing System Calls o Creating User Events in Your Program o 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: o Tracing Dynamic Link Libraries (DLLs) o Tracing System Calls o Creating User Events in Your Program o 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 CPPWPA3.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. Compile: icc /c /Ti /Gh sample.cpp Link: ilink /DE /NOE sample.obj cppwpa3.obj Related Information o IBM C/C++ Tools: Programming Guide o Tracing Dynamic Link Libraries (DLLs) o Tracing System Calls o Creating User Events in Your Program o Starting and Stopping the Performance Analyzer from Your Program. ΓòÉΓòÉΓòÉ 3.2. Tracing Dynamic Link Libraries (DLLs) ΓòÉΓòÉΓòÉ You can trace statically or dynamically linked 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 loaded DLLs. ΓòÉΓòÉΓòÉ 3.3. Tracing System Calls ΓòÉΓòÉΓòÉ If you want to trace system API calls, specify the Performance Analyzer libraries before the system libraries in your link statement. You can link one or more libraries. Notes: 1. Output produced by cout stream objects is stored in the operating system's buffer and is not shown until tracing has stopped. System API calls for the cout stream are not displayed in the trace file. 2. It is not possible to trace events in the KERNEL32 intercept library only. The Performance Analyzer looks for at least one event from your program before logging these call events. If you link the _KERNEL.LIB library, compile your program with the /Gh and /Ti options to include events from your program in the trace file. 3. If you compile your source with the /Gd- switch, the trace file will contain all of the system calls called by your code and the system calls called by VisualAge C++ runtime calls. To avoid tracing calls made by runtime calls, use the /Gd+ switch. The Performance Analyzer libraries are as follows. Each library listed also has an associated DLL. o _KERNEL.LIB o _USER32.LIB o _GDI32.LIB Important: The order in which these libraries are specified in the link statement is critical. If the replacement libraries do not precede the system libraries in the link statement, the Performance Analyzer will not interpret and trace the API calls. Related Information o Compiling and Linking Your Program ΓòÉΓòÉΓòÉ 3.3.1. Traced Functions in Intercept Libraries ΓòÉΓòÉΓòÉ The following functions appear in the Performance Analyzer intercept libraries. The Performance Analyzer will trace these functions when the intercept libraries are linked properly. Notes: 1. Output produced by cout stream objects is stored in the operating system's buffer and is not shown until tracing has stopped. System API calls for the cout stream are not displayed in the trace file. 2. It is not possible to trace events in the KERNEL32 intercept library only. The Performance Analyzer looks for at least one event from your program before logging these call events. If you link the _KERNEL.LIB library, compile your program with the /Gh and /Ti options to include events from your program in the trace file. 3. If you compile your source with the /Gd- switch, the trace file will contain all of the system calls called by your code and the system calls called by VisualAge C++ runtime calls. To avoid tracing calls made by runtime calls, use the /Gd+ switch. The functions in the following list appear in the _KERNEL.LIB intercept library: AddAtomA AddAtomW AllocConsole AreFileApisANSI BackupRead BackupSeek BackupWrite Beep BeginUpdateResourceA BeginUpdateResourceW BuildCommDCBA BuildCommDCBAndTimeoutsA BuildCommDCBAndTimeoutsW BuildCommDCBW CallNamedPipeA CallNamedPipeW ClearCommBreak ClearCommError CloseHandle CommConfigDialogA CommConfigDialogW CompareFileTime CompareStringA CompareStringW ConnectNamedPipe ContinueDebugEvent ConvertDefaultLocale CopyFileA CopyFileW CreateConsoleScreenBuffer CreateDirectoryA CreateDirectoryExA CreateDirectoryExW CreateDirectoryW CreateEventA CreateEventW CreateFileA CreateFileMappingA CreateFileMappingW CreateFileW CreateIoCompletionPort CreateMailslotA CreateMailslotW CreateMutexA CreateMutexW CreateNamedPipeA CreateNamedPipeW CreatePipe CreateProcessA CreateProcessW CreateRemoteThread CreateSemaphoreA CreateSemaphoreW CreateTapePartition CreateThread DebugActiveProcess DebugBreak DefineDosDeviceA DefineDosDeviceW DeleteAtom DeleteCriticalSection DeleteFileA DeleteFileW DeviceIoControl DisableThreadLibraryCalls DisconnectNamedPipe DosDateTimeToFileTime DuplicateHandle EndUpdateResourceA EndUpdateResourceW EnumCalendarInfoA EnumCalendarInfoW EnumDateFormatsA EnumDateFormatsW EnumResourceLanguagesA EnumResourceLanguagesW EnumResourceNamesA EnumResourceNamesW EnumResourceTypesA EnumResourceTypesW EnumSystemCodePagesA EnumSystemCodePagesW EnumSystemLocalesA EnumSystemLocalesW EnumTimeFormatsA EnumTimeFormatsW EraseTape EscapeCommFunction ExitProcess ExitThread ExpandEnvironmentStringsA ExpandEnvironmentStringsW FatalAppExitA FatalAppExitW FatalExit FileTimeToDosDateTime FileTimeToLocalFileTime FileTimeToSystemTime FillConsoleOutputAttribute FillConsoleOutputCharacterA FillConsoleOutputCharacterW FindAtomA FindAtomW FindClose FindCloseChangeNotification FindFirstChangeNotificationA FindFirstChangeNotificationW FindFirstFileA FindFirstFileW FindNextChangeNotification FindNextFileA FindNextFileW FindResourceA FindResourceExA FindResourceExW FindResourceW FlushConsoleInputBuffer FlushFileBuffers FlushInstructionCache FlushViewOfFile FoldStringA FoldStringW FormatMessageA FormatMessageW FreeConsole FreeEnvironmentStringsA FreeEnvironmentStringsW FreeLibrary FreeLibraryAndExitThread FreeResource GenerateConsoleCtrlEvent GetACP GetAtomNameA GetAtomNameW GetBinaryTypeA GetBinaryTypeW GetCPInfo GetCommConfig GetCommMask GetCommModemStatus GetCommProperties GetCommState GetCommTimeouts GetCommandLineA GetCommandLineW GetCompressedFileSizeA GetCompressedFileSizeW GetComputerNameA GetComputerNameW GetConsoleCP GetConsoleCursorInfo GetConsoleMode GetConsoleOutputCP GetConsoleScreenBufferInfo GetConsoleTitleA GetConsoleTitleW GetCurrencyFormatA GetCurrencyFormatW GetCurrentDirectoryA GetCurrentDirectoryW GetCurrentProcess GetCurrentProcessId GetCurrentThread GetDateFormatA GetDateFormatW GetDefaultCommConfigA GetDefaultCommConfigW GetDiskFreeSpaceA GetDiskFreeSpaceW GetDriveTypeA GetDriveTypeW GetEnvironmentStrings GetEnvironmentStringsA GetEnvironmentStringsW GetEnvironmentVariableA GetEnvironmentVariableW GetExitCodeProcess GetExitCodeThread GetFileAttributesA GetFileAttributesW GetFileInformationByHandle GetFileSize GetFileTime GetFileType GetFullPathNameA GetFullPathNameW GetHandleInformation GetLargestConsoleWindowSize GetLastError GetLocalTime GetLocaleInfoA GetLocaleInfoW GetLogicalDriveStringsA GetLogicalDriveStringsW GetLogicalDrives GetMailslotInfo GetModuleFileNameA GetModuleFileNameW GetModuleHandleA GetModuleHandleW GetNamedPipeHandleStateA GetNamedPipeHandleStateW GetNamedPipeInfo GetNumberFormatA GetNumberFormatW GetNumberOfConsoleInputEvents GetNumberOfConsoleMouseButtons GetOEMCP GetOverlappedResult GetPriorityClass GetPrivateProfileIntA GetPrivateProfileIntW GetPrivateProfileSectionA GetPrivateProfileSectionNamesA GetPrivateProfileSectionNamesW GetPrivateProfileSectionW GetPrivateProfileStringA GetPrivateProfileStringW GetPrivateProfileStructA GetPrivateProfileStructW GetProcessAffinityMask GetProcessHeap GetProcessHeaps GetProcessShutdownParameters GetProcessTimes GetProcessVersion GetProcessWorkingSetSize GetProfileIntA GetProfileIntW GetProfileSectionA GetProfileSectionW GetProfileStringA GetProfileStringW GetQueuedCompletionStatus GetShortPathNameA GetShortPathNameW GetStartupInfoA GetStartupInfoW GetStdHandle GetStringTypeA GetStringTypeExA GetStringTypeExW GetStringTypeW GetSystemDefaultLCID GetSystemDefaultLangID GetSystemDirectoryA GetSystemDirectoryW GetSystemInfo GetSystemPowerStatus GetSystemTime GetSystemTimeAdjustment GetSystemTimeAsFileTime GetTapeParameters GetTapePosition GetTapeStatus GetTempFileNameA GetTempFileNameW GetTempPathA GetTempPathW GetThreadContext GetThreadLocale GetThreadPriority GetThreadSelectorEntry GetThreadTimes GetTickCount GetTimeFormatA GetTimeFormatW GetTimeZoneInformation GetUserDefaultLCID GetUserDefaultLangID GetVersion GetVersionExA GetVersionExW GetVolumeInformationA GetVolumeInformationW GetWindowsDirectoryA GetWindowsDirectoryW GlobalAddAtomA GlobalAddAtomW GlobalAlloc GlobalCompact GlobalDeleteAtom GlobalFindAtomA GlobalFindAtomW GlobalFix GlobalFlags GlobalFree GlobalGetAtomNameA GlobalGetAtomNameW GlobalHandle GlobalLock GlobalMemoryStatus GlobalReAlloc GlobalSize GlobalUnWire GlobalUnfix GlobalUnlock GlobalWire HeapAlloc HeapCompact HeapCreate HeapDestroy HeapFree HeapLock HeapReAlloc HeapSize HeapUnlock HeapValidate HeapWalk InitAtomTable InterlockedDecrement InterlockedExchange InterlockedIncrement IsBadCodePtr IsBadHugeReadPtr IsBadHugeWritePtr IsBadReadPtr IsBadStringPtrA IsBadStringPtrW IsBadWritePtr IsDBCSLeadByte IsDBCSLeadByteEx IsValidCodePage IsValidLocale LCMapStringA LCMapStringW LoadLibraryExA LoadLibraryExW LoadModule LoadResource LocalAlloc LocalCompact LocalFileTimeToFileTime LocalFlags LocalFree LocalHandle LocalLock LocalReAlloc LocalShrink LocalSize LocalUnlock LockFile LockFileEx LockResource MapViewOfFile MapViewOfFileEx MoveFileA MoveFileExA MoveFileExW MoveFileW MulDiv MultiByteToWideChar OpenEventA OpenEventW OpenFile OpenFileMappingA OpenFileMappingW OpenMutexA OpenMutexW OpenProcess OpenSemaphoreA OpenSemaphoreW OutputDebugStringA OutputDebugStringW PeekConsoleInputA PeekConsoleInputW PeekNamedPipe PostQueuedCompletionStatus PrepareTape PulseEvent PurgeComm QueryDosDeviceA QueryDosDeviceW QueryPerformanceCounter QueryPerformanceFrequency RaiseException ReadConsoleA ReadConsoleInputA ReadConsoleInputW ReadConsoleOutputA ReadConsoleOutputAttribute ReadConsoleOutputCharacterA ReadConsoleOutputCharacterW ReadConsoleOutputW ReadConsoleW ReadFile ReadFileEx ReadProcessMemory ReleaseMutex ReleaseSemaphore RemoveDirectoryA RemoveDirectoryW ResetEvent ResumeThread RtlFillMemory RtlMoveMemory RtlZeroMemory ScrollConsoleScreenBufferA ScrollConsoleScreenBufferW SearchPathA SearchPathW SetCommBreak SetCommConfig SetCommMask SetCommState SetCommTimeouts SetComputerNameA SetComputerNameW SetConsoleActiveScreenBuffer SetConsoleCP SetConsoleCtrlHandler SetConsoleCursorInfo SetConsoleCursorPosition SetConsoleMode SetConsoleOutputCP SetConsoleScreenBufferSize SetConsoleTextAttribute SetConsoleTitleA SetConsoleTitleW SetConsoleWindowInfo SetCurrentDirectoryA SetCurrentDirectoryW SetDefaultCommConfigA SetDefaultCommConfigW SetEndOfFile SetEnvironmentVariableA SetEnvironmentVariableW SetErrorMode SetEvent SetFileApisToANSI SetFileApisToOEM SetFileAttributesA SetFileAttributesW SetFilePointer SetFileTime SetHandleCount SetHandleInformation SetLastError SetLocalTime SetLocaleInfoA SetLocaleInfoW SetMailslotInfo SetNamedPipeHandleState SetPriorityClass SetProcessShutdownParameters SetProcessWorkingSetSize SetStdHandle SetSystemPowerState SetSystemTime SetSystemTimeAdjustment SetTapeParameters SetTapePosition SetThreadAffinityMask SetThreadContext SetThreadLocale SetThreadPriority SetTimeZoneInformation SetUnhandledExceptionFilter SetVolumeLabelA SetVolumeLabelW SetupComm SizeofResource Sleep SleepEx SuspendThread SystemTimeToFileTime SystemTimeToTzSpecificLocalTime TerminateProcess TerminateThread TlsAlloc TlsFree TlsGetValue TlsSetValue TransactNamedPipe TransmitCommChar UnhandledExceptionFilter UnlockFile UnlockFileEx UnmapViewOfFile UpdateResourceA UpdateResourceW VerLanguageNameA VerLanguageNameW VirtualAlloc VirtualFree VirtualLock VirtualProtect VirtualProtectEx VirtualQuery VirtualQueryEx VirtualUnlock WaitCommEvent WaitForDebugEvent WaitForMultipleObjects WaitForMultipleObjectsEx WaitForSingleObject WaitForSingleObjectEx WaitNamedPipeA WaitNamedPipeW WideCharToMultiByte WinExec WriteConsoleA WriteConsoleInputA WriteConsoleInputW WriteConsoleOutputA WriteConsoleOutputAttribute WriteConsoleOutputCharacterA WriteConsoleOutputCharacterW WriteConsoleOutputW WriteConsoleW WriteFile WriteFileEx WritePrivateProfileSectionA WritePrivateProfileSectionW WritePrivateProfileStringA WritePrivateProfileStringW WritePrivateProfileStructA WritePrivateProfileStructW WriteProcessMemory WriteProfileSectionA WriteProfileSectionW WriteProfileStringA WriteProfileStringW WriteTapemark _hread _hwrite _lclose _lcreat _llseek _lopen _lread _lwrite lstrcatA lstrcatW lstrcmpA lstrcmpW lstrcmpiA lstrcmpiW lstrcpyA lstrcpyW lstrcpynA lstrcpynW lstrlenA lstrlenW The functions in the following list appear in the _GDI32.LIB intercept library: AbortDoc AbortPath AddFontResourceA AddFontResourceW AngleArc AnimatePalette Arc ArcTo BeginPath BitBlt CancelDC CheckColorsInGamut ChoosePixelFormat Chord CloseEnhMetaFile CloseFigure CloseMetaFile ColorMatchToTarget CombineRgn CombineTransform CopyEnhMetaFileA CopyEnhMetaFileW CopyMetaFileA CopyMetaFileW CreateBitmap CreateBitmapIndirect CreateBrushIndirect CreateColorSpaceA CreateColorSpaceW CreateCompatibleBitmap CreateCompatibleDC CreateDCA CreateDCW CreateDIBPatternBrush CreateDIBPatternBrushPt CreateDIBSection CreateDIBitmap CreateDiscardableBitmap CreateEllipticRgn CreateEllipticRgnIndirect CreateEnhMetaFileA CreateEnhMetaFileW CreateFontA CreateFontIndirectA CreateFontIndirectW CreateFontW CreateHalftonePalette CreateHatchBrush CreateICA CreateICW CreateMetaFileA CreateMetaFileW CreatePalette CreatePatternBrush CreatePen CreatePenIndirect CreatePolyPolygonRgn CreatePolygonRgn CreateRectRgn CreateRectRgnIndirect CreateRoundRectRgn CreateScalableFontResourceA CreateScalableFontResourceW CreateSolidBrush DPtoLP DeleteColorSpace DeleteDC DeleteEnhMetaFile DeleteMetaFile DeleteObject DescribePixelFormat DrawEscape Ellipse EndDoc EndPage EndPath EnumEnhMetaFile EnumFontFamiliesA EnumFontFamiliesExA EnumFontFamiliesExW EnumFontFamiliesW EnumFontsA EnumFontsW EnumICMProfilesA EnumICMProfilesW EnumMetaFile EnumObjects EqualRgn Escape ExcludeClipRect ExtCreatePen ExtCreateRegion ExtEscape ExtFloodFill ExtSelectClipRgn ExtTextOutA ExtTextOutW FillPath FillRgn FixBrushOrgEx FlattenPath FloodFill FrameRgn GdiComment GetArcDirection GetAspectRatioFilterEx GetBitmapBits GetBitmapDimensionEx GetBkColor GetBkMode GetBoundsRect GetBrushOrgEx GetCharABCWidthsA GetCharABCWidthsFloatA GetCharABCWidthsFloatW GetCharABCWidthsW GetCharWidth32A GetCharWidth32W GetCharWidthA GetCharWidthFloatA GetCharWidthFloatW GetCharWidthW GetCharacterPlacementA GetCharacterPlacementW GetClipBox GetClipRgn GetColorAdjustment GetColorSpace GetCurrentObject GetCurrentPositionEx GetDCOrgEx GetDIBColorTable GetDIBits GetDeviceCaps GetDeviceGammaRamp GetEnhMetaFileA GetEnhMetaFileBits GetEnhMetaFileDescriptionA GetEnhMetaFileDescriptionW GetEnhMetaFileHeader GetEnhMetaFilePaletteEntries GetEnhMetaFileW GetFontData GetFontLanguageInfo GetGlyphOutlineA GetGlyphOutlineW GetGraphicsMode GetICMProfileA GetICMProfileW GetKerningPairsA GetKerningPairsW GetLogColorSpaceA GetLogColorSpaceW GetMapMode GetMetaFileA GetMetaFileBitsEx GetMetaFileW GetMetaRgn GetMiterLimit GetNearestColor GetNearestPaletteIndex GetObjectA GetObjectType GetObjectW GetOutlineTextMetricsA GetOutlineTextMetricsW GetPaletteEntries GetPath GetPixel GetPixelFormat GetPolyFillMode GetROP2 GetRasterizerCaps GetRegionData GetRgnBox GetStockObject GetStretchBltMode GetSystemPaletteEntries GetSystemPaletteUse GetTextAlign GetTextCharacterExtra GetTextCharset GetTextCharsetInfo GetTextColor GetTextExtentExPointA GetTextExtentExPointW GetTextExtentPoint32A GetTextExtentPoint32W GetTextExtentPointA GetTextExtentPointW GetTextFaceA GetTextFaceW GetTextMetricsA GetTextMetricsW GetViewportExtEx GetViewportOrgEx GetWinMetaFileBits GetWindowExtEx GetWindowOrgEx GetWorldTransform IntersectClipRect InvertRgn LPtoDP LineDDA LineTo MaskBlt ModifyWorldTransform MoveToEx OffsetClipRgn OffsetRgn OffsetViewportOrgEx OffsetWindowOrgEx PaintRgn PatBlt PathToRegion Pie PlayEnhMetaFile PlayEnhMetaFileRecord PlayMetaFile PlayMetaFileRecord PlgBlt PolyBezier PolyBezierTo PolyDraw PolyPolygon PolyPolyline PolyTextOutA PolyTextOutW Polygon Polyline PolylineTo PtInRegion PtVisible RealizePalette RectInRegion RectVisible Rectangle RemoveFontResourceA RemoveFontResourceW ResetDCA ResetDCW ResizePalette RestoreDC RoundRect SaveDC ScaleViewportExtEx ScaleWindowExtEx SelectClipPath SelectClipRgn SelectObject SelectPalette SetAbortProc SetArcDirection SetBitmapBits SetBitmapDimensionEx SetBkColor SetBkMode SetBoundsRect SetBrushOrgEx SetColorAdjustment SetColorSpace SetDIBColorTable SetDIBits SetDIBitsToDevice SetDeviceGammaRamp SetEnhMetaFileBits SetGraphicsMode SetICMMode SetICMProfileA SetICMProfileW SetMapMode SetMapperFlags SetMetaFileBitsEx SetMetaRgn SetMiterLimit SetPaletteEntries SetPixel SetPixelFormat SetPixelV SetPolyFillMode SetROP2 SetRectRgn SetStretchBltMode SetSystemPaletteUse SetTextAlign SetTextCharacterExtra SetTextColor SetTextJustification SetViewportExtEx SetViewportOrgEx SetWinMetaFileBits SetWindowExtEx SetWindowOrgEx SetWorldTransform StartDocA StartDocW StartPage StretchBlt StretchDIBits StrokeAndFillPath StrokePath SwapBuffers TextOutA TextOutW TranslateCharsetInfo UnrealizeObject UpdateColors UpdateICMRegKeyA UpdateICMRegKeyW WidenPath The functions in the following list appear in the _USER32.LIB intercept library : ActivateKeyboardLayout AdjustWindowRect AdjustWindowRectEx AnyPopup AppendMenuA AppendMenuW ArrangeIconicWindows AttachThreadInput BeginDeferWindowPos BeginPaint BringWindowToTop BroadcastSystemMessage CallMsgFilterA CallMsgFilterW CallNextHookEx CallWindowProcA CallWindowProcW CascadeWindows ChangeClipboardChain ChangeDisplaySettingsA ChangeDisplaySettingsW ChangeMenuA ChangeMenuW CharLowerA CharLowerBuffA CharLowerBuffW CharLowerW CharNextA CharNextExA CharNextW CharPrevA CharPrevExA CharPrevW CharToOemA CharToOemBuffA CharToOemBuffW CharToOemW CharUpperA CharUpperBuffA CharUpperBuffW CharUpperW CheckDlgButton CheckMenuItem CheckMenuRadioItem CheckRadioButton ChildWindowFromPoint ChildWindowFromPointEx ClientToScreen ClipCursor CloseClipboard CloseDesktop CloseWindow CloseWindowStation CopyAcceleratorTableA CopyAcceleratorTableW CopyIcon CopyImage CopyRect CountClipboardFormats CreateAcceleratorTableA CreateAcceleratorTableW CreateCaret CreateCursor CreateDesktopA CreateDesktopW CreateDialogIndirectParamA CreateDialogIndirectParamW CreateDialogParamA CreateDialogParamW CreateIcon CreateIconFromResource CreateIconFromResourceEx CreateIconIndirect CreateMDIWindowA CreateMDIWindowW CreateMenu CreatePopupMenu CreateWindowExA CreateWindowExW CreateWindowStationA CreateWindowStationW DdeAbandonTransaction DdeAccessData DdeAddData DdeClientTransaction DdeCmpStringHandles DdeConnect DdeConnectList DdeCreateDataHandle DdeCreateStringHandleA DdeCreateStringHandleW DdeDisconnect DdeDisconnectList DdeEnableCallback DdeFreeDataHandle DdeFreeStringHandle DdeGetData DdeGetLastError DdeImpersonateClient DdeInitializeA DdeInitializeW DdeKeepStringHandle DdeNameService DdePostAdvise DdeQueryConvInfo DdeQueryNextServer DdeQueryStringA DdeQueryStringW DdeReconnect DdeSetQualityOfService DdeSetUserHandle DdeUnaccessData DdeUninitialize DefDlgProcA DefDlgProcW DefFrameProcA DefFrameProcW DefMDIChildProcA DefMDIChildProcW DefWindowProcA DefWindowProcW DeferWindowPos DeleteMenu DestroyAcceleratorTable DestroyCaret DestroyCursor DestroyIcon DestroyMenu DestroyWindow DialogBoxIndirectParamA DialogBoxIndirectParamW DialogBoxParamA DialogBoxParamW DispatchMessageA DispatchMessageW DlgDirListA DlgDirListComboBoxA DlgDirListComboBoxW DlgDirListW DlgDirSelectComboBoxExA DlgDirSelectComboBoxExW DlgDirSelectExA DlgDirSelectExW DragDetect DragObject DrawAnimatedRects DrawCaption DrawEdge DrawFocusRect DrawFrameControl DrawIcon DrawIconEx DrawMenuBar DrawStateA DrawStateW DrawTextA DrawTextExA DrawTextExW DrawTextW EmptyClipboard EnableMenuItem EnableScrollBar EnableWindow EndDeferWindowPos EndDialog EndPaint EnumChildWindows EnumClipboardFormats EnumDesktopsA EnumDesktopsW EnumDesktopWindows EnumDisplaySettingsA EnumDisplaySettingsW EnumPropsA EnumPropsExA EnumPropsExW EnumPropsW EnumThreadWindows EnumWindowStationsA EnumWindowStationsW EnumWindows EqualRect ExcludeUpdateRgn ExitWindowsEx FillRect FindWindowA FindWindowExA FindWindowExW FindWindowW FlashWindow FrameRect FreeDDElParam GetActiveWindow GetAsyncKeyState GetCapture GetCaretBlinkTime GetCaretPos GetClassInfoA GetClassInfoExA GetClassInfoExW GetClassInfoW GetClassLongA GetClassLongW GetClassNameA GetClassNameW GetClassWord GetClientRect GetClipCursor GetClipboardData GetClipboardFormatNameA GetClipboardFormatNameW GetClipboardOwner GetClipboardViewer GetCursor GetCursorPos GetDC GetDCEx GetDesktopWindow GetDialogBaseUnits GetDlgCtrlID GetDlgItem GetDlgItemInt GetDlgItemTextA GetDlgItemTextW GetDoubleClickTime GetFocus GetForegroundWindow GetIconInfo GetInputState GetKBCodePage GetKeyNameTextA GetKeyNameTextW GetKeyState GetKeyboardLayout GetKeyboardLayoutList GetKeyboardLayoutNameA GetKeyboardLayoutNameW GetKeyboardState GetKeyboardType GetLastActivePopup GetMenu GetMenuCheckMarkDimensions GetMenuContextHelpId GetMenuDefaultItem GetMenuItemCount GetMenuItemID GetMenuItemInfoA GetMenuItemInfoW GetMenuItemRect GetMenuState GetMenuStringA GetMenuStringW GetMessageA GetMessageExtraInfo GetMessagePos GetMessageTime GetMessageW GetNextDlgGroupItem GetNextDlgTabItem GetOpenClipboardWindow GetParent GetPriorityClipboardFormat GetProcessWindowStation GetPropA GetPropW GetQueueStatus GetScrollInfo GetScrollPos GetScrollRange GetSubMenu GetSysColor GetSysColorBrush GetSystemMenu GetSystemMetrics GetTabbedTextExtentA GetTabbedTextExtentW GetThreadDesktop GetTopWindow GetUpdateRect GetUpdateRgn GetUserObjectInformationA GetUserObjectInformationW GetUserObjectSecurity GetWindow GetWindowContextHelpId GetWindowDC GetWindowLongA GetWindowLongW GetWindowPlacement GetWindowRect GetWindowRgn GetWindowTextA GetWindowTextLengthA GetWindowTextLengthW GetWindowTextW GetWindowThreadProcessId GetWindowWord GrayStringA GrayStringW HideCaret HiliteMenuItem ImpersonateDdeClientWindow InSendMessage InflateRect InsertMenuA InsertMenuItemA InsertMenuItemW InsertMenuW IntersectRect InvalidateRect InvalidateRgn InvertRect IsCharAlphaA IsCharAlphaNumericA IsCharAlphaNumericW IsCharAlphaW IsCharLowerA IsCharLowerW IsCharUpperA IsCharUpperW IsChild IsClipboardFormatAvailable IsDialogMessageA IsDialogMessageW IsDlgButtonChecked IsIconic IsMenu IsRectEmpty IsWindow IsWindowEnabled IsWindowUnicode IsWindowVisible IsZoomed KillTimer LoadAcceleratorsA LoadAcceleratorsW LoadBitmapA LoadBitmapW LoadCursorA LoadCursorFromFileA LoadCursorFromFileW LoadCursorW LoadIconA LoadIconW LoadImageA LoadImageW LoadKeyboardLayoutA LoadKeyboardLayoutW LoadMenuA LoadMenuIndirectA LoadMenuIndirectW LoadMenuW LoadStringA LoadStringW LockWindowUpdate LookupIconIdFromDirectory LookupIconIdFromDirectoryEx MapDialogRect MapVirtualKeyA MapVirtualKeyExA MapVirtualKeyExW MapVirtualKeyW MapWindowPoints MenuItemFromPoint MessageBeep MessageBoxA MessageBoxExA MessageBoxExW MessageBoxIndirectA MessageBoxIndirectW MessageBoxW ModifyMenuA ModifyMenuW MoveWindow MsgWaitForMultipleObjects OemKeyScan OemToCharA OemToCharBuffA OemToCharBuffW OemToCharW OffsetRect OpenClipboard OpenDesktopA OpenDesktopW OpenIcon OpenInputDesktop OpenWindowStationA OpenWindowStationW PackDDElParam PaintDesktop PeekMessageA PeekMessageW PostMessageA PostMessageW PostQuitMessage PostThreadMessageA PostThreadMessageW PtInRect RedrawWindow RegisterClassA RegisterClassExA RegisterClassExW RegisterClassW RegisterClipboardFormatA RegisterClipboardFormatW RegisterHotKey RegisterWindowMessageA RegisterWindowMessageW ReleaseCapture ReleaseDC RemoveMenu RemovePropA RemovePropW ReplyMessage ReuseDDElParam ScreenToClient ScrollDC ScrollWindow ScrollWindowEx SendDlgItemMessageA SendDlgItemMessageW SendMessageA SendMessageCallbackA SendMessageCallbackW SendMessageTimeoutA SendMessageTimeoutW SendMessageW SendNotifyMessageA SendNotifyMessageW SetActiveWindow SetCapture SetCaretBlinkTime SetCaretPos SetClassLongA SetClassLongW SetClassWord SetClipboardData SetClipboardViewer SetCursor SetCursorPos SetDebugErrorLevel SetDlgItemInt SetDlgItemTextA SetDlgItemTextW SetDoubleClickTime SetFocus SetForegroundWindow SetKeyboardState SetLastErrorEx SetMenu SetMenuContextHelpId SetMenuDefaultItem SetMenuItemBitmaps SetMenuItemInfoA SetMenuItemInfoW SetMessageExtraInfo SetMessageQueue SetParent SetProcessWindowStation SetPropA SetPropW SetRect SetRectEmpty SetScrollInfo SetScrollPos SetScrollRange SetSysColors SetSystemCursor SetThreadDesktop SetTimer SetUserObjectInformationA SetUserObjectInformationW SetUserObjectSecurity SetWindowContextHelpId SetWindowLongA SetWindowLongW SetWindowPlacement SetWindowPos SetWindowRgn SetWindowTextA SetWindowTextW SetWindowWord SetWindowsHookA SetWindowsHookExA SetWindowsHookExW SetWindowsHookW ShowCaret ShowCursor ShowOwnedPopups ShowScrollBar ShowWindow ShowWindowAsync SubtractRect SwapMouseButton SwitchDesktop SystemParametersInfoA SystemParametersInfoW TabbedTextOutA TabbedTextOutW TileWindows ToAscii ToAsciiEx ToUnicode TrackPopupMenu TrackPopupMenuEx TranslateAcceleratorA TranslateAcceleratorW TranslateMDISysAccel TranslateMessage UnhookWindowsHook UnhookWindowsHookEx UnionRect UnloadKeyboardLayout UnpackDDElParam UnregisterClassA UnregisterClassW UnregisterHotKey UpdateWindow ValidateRect ValidateRgn VkKeyScanA VkKeyScanExA VkKeyScanExW VkKeyScanW WaitForInputIdle WaitMessage WinHelpA WinHelpW WindowFromDC WindowFromPoint keybd_event mouse_event wvsprintfA wvsprintfW ΓòÉΓòÉΓòÉ 3.4. Creating User Events in Your Program ΓòÉΓòÉΓòÉ The CPPWPA3.OBJ file contains an entry point called PERF that accepts calls from the program you are tracing. Calls to the PERF entry point at execution 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 <iperf.h> Note: If you want to insert the prototype yourself, the prototypes for C and C++ programs are as follows: C Prototype void PERF (const char* string); C++ Prototype extern "C" {void PERF(const char* 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 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 o Compiling and Linking Your Program o Tracing System Calls o Starting and Stopping the Performance Analyzer from Your Program o Annotate Window o Call Nesting diagram o Statistics diagram o Time Line diagram o Application Monitor Window o IBM C/C++ Tools: Programming Guide. ΓòÉΓòÉΓòÉ 3.5. Starting and Stopping the Performance Analyzer from Your Program ΓòÉΓòÉΓòÉ The CPPWPA3.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 <iperf.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 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 o Compiling and Linking Your Program o Tracing System Calls o Annotate Window o Call Nesting diagram o Statistics diagram o Time Line diagram o Application Monitor Window o IBM C/C++ Tools: Programming Guide. ΓòÉΓòÉΓòÉ 4. Starting the Performance Analyzer from a Command Line ΓòÉΓòÉΓòÉ 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: o Trace an executable o Analyze an existing trace file. o Display the Performance Analyzer's main control window Tracing an Executable o If you have an executable you want to trace, you can start the analyzer from a command line, a command file (CMD), or a batch file (BAT) by entering: iperf 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. o You can also include the /go option in the command: iperf /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 a command file. This is optional. myprog Represents an executable file name. This is required when the go/ option is specified. parms Represents parameters associated with the myprog executable. 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 a command line, a command file (CMD), or a batch file (BAT) by entering: iperf /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: iperf From this window, you can start either tracing an executable or analyzing an existing trace file. See Creating a Trace File to continue. Related Information o Introducing the Performance Analyzer o Preparing Your Program for the Performance Analyzer o Performance Analyzer - Window Manager Window o Creating a Trace File o 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. Open a project folder in the WorkFrame window. 3. Compile and link your program with Performance Analyzer options. Note: This is described in Compiling and Linking Your Program. 4. Highlight an object that represents an executable file or a trace file. 5. Click mouse button 2 on the highlighted object to display a pop-up menu. 6. Select Analyze. Related Information o Introducing the Performance Analyzer o Preparing Your Program for the Performance Analyzer o Performance Analyzer - Window Manager Window o Creating a Trace File o Analyzing a Trace File o Search Paths... Choice o Project Menu o 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: o File menu on the Performance Analyzer - Window Manager window o Application menu on the Trace Generation window o 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 o Performance Analyzer - Window Manager Window o Quick Exit Choice o 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: o Call Nesting o Dynamic Call Graph o Execution Density o Statistics o 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. Note: If you open your trace file in a diagram and find that the file does not contain any trace events, your application may have been unable to locate CPPWPA3.DLL when you created the trace file. To correct this, change your path to point to the location of CPPWPA3.DLL (probably in the DLL subdirectory where you installed VisualAge for C++), and then recreate your trace file. Related Information o Compiling and Linking Your Program o Create Trace Window o Trace Generation Window o Analyze Trace Window. ΓòÉΓòÉΓòÉ 8. Creating a Customized Trace File ΓòÉΓòÉΓòÉ By default, the Performance Analyzer generates event information for every function executed that has been compiled and linked with the proper options. However, this sometimes causes the trace file to become large and difficult to manage. To allow you to control the size of your trace file, the Performance Analyzer provides the following parameters, which you can set prior to running your program. The following parameters affect the size of the trace file: o Enabled or disabled state of components o Call depth setting for each thread o Time stamp setting o Trigger settings. o Buffer wrap setting. Although they do not affect the size of your trace file, the following items can also be customized: o Trace file name. 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. o Trace file description. 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 o Preparing Your Program for the Performance Analyzer o Compiling and Linking Your Program o Performance Analyzer - Window Manager Window o 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, a 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: o An EXE, a DLL, or an OBJ file, the Performance Analyzer disables all functions within the selected file and removes any triggers set on functions within the file. o A function, the Performance Analyzer removes any trigger set on it. When you enable: o An EXE, a DLL, or an 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 starts tracing when it reaches the triggered function and continues tracing until it receives a return from that function. If no triggers are set, the Performance Analyzer traces all enabled components. Remove trigger Removes a trigger on a function. This choice is available when you select a function that has a trigger set on it. Note: If triggers are set, the Performance Analyzer starts tracing when it reaches the triggered function and continues tracing until it receives a return from that function. 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: o 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. o Double-click on the file name or icon of the component you want to enable or disable. o Click mouse button 2 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: o Green (with no slash mark), the component is enabled. o Red (with a slash mark), the component is disabled. o White, the component cannot be traced. ΓòÉΓòÉΓòÉ 8.2. Selecting the Call Depth for Each Thread ΓòÉΓòÉΓòÉ You may want to specify the call depth that you want to trace in order to isolate an area of interest and reduce the amount of trace data. Select Call depth... from the Options menu on the Trace Generation window to select the nesting depth of function calls or to specify threads that you want to include in 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. Related Information o Call Depth... Choice o Trace Generation Window o 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. Disabling Time stamp events causes your trace file to be smaller because time stamps are not stored. It does not limit the number of events collected in the trace file. While logging events, the Performance Analyzer adds a small amount of overhead time to the normal execution time of the program through buffer flushing and writing to disk, and through the monitoring of events. Although the time added is negligible, the Performance Analyzer attempts to remove it from the timings reported in the diagrams. Therefore, the timings you see in the diagrams represent your program's actual execution time as nearly as possible. 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: o You can only view the trace file in the Dynamic Call Graph, Call Nesting, and Statistics diagrams. o All nodes in the Dynamic Call Graph will be the same size and color. o Time data (such as execution time and time on stack) will not be present in either the diagrams or their related dialogs. Related Information o Time Stamp Events Choice o Understanding Overhead Time o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 8.4. Setting and Removing Triggers ΓòÉΓòÉΓòÉ A trigger turns tracing on when the function 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: o If triggers are set, the Performance Analyzer starts tracing when it reaches the triggered function and continues tracing until it receives a return from that function. If no triggers are set, the Performance Analyzer traces all enabled components. o If a trigger function is nested within another trigger function, tracing is turned off only after the outer function returns. o 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. o If you disable an EXE, a DLL, or an object (OBJ) file, the Performance Analyzer disables all functions within the selected file and removes any triggers set on functions within the file. o If you set a trigger on a disabled function, the Performance Analyzer enables the function. o If you disable a function, the Performance Analyzer removes any trigger set on it. Related Information o Set Trigger Choice o Remove Trigger Choice o Function Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ 8.5. Enabling and Disabling Buffer Wrap ΓòÉΓòÉΓòÉ Select Buffer wrap from the Options menu on the Trace Generation window to enable or disable 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 Buffer wrap is enabled, the Performance Analyzer overwrites older events in the buffer with newer ones. Since the buffer is flushed only when the program ends, the trace file is smaller, but some trace data is lost. The default setting for Buffer wrap is disabled. A check mark appears next to the choice when it is enabled. The check mark does not appear when the choice is disabled. If Buffer wrap is disabled and the trace buffer becomes full, the Performance Analyzer: 1. Pauses 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. Resumes the program. Note: Time stamping the buffer flush allows the diagrams to remove the buffer-flushing overhead time. Related Information o Buffer Wrap Choice o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 8.6. 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 o Name Trace File... Choice o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 8.7. 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 o Save Choice o Trace Generation Window o 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 the icon the Performance Analyzer uses to represent each diagram throughout the application: Call Nesting Useful for diagnosing specific performance problems. For example, you might use this diagram to see what led up to a thread switch. The Time Line diagram is useful in correlation with this diagram. For example, you can mark a function call in this diagram, and then correlate it to the Time Line diagram. The correlated Time Line diagram shows you when the function call occurred and how long it lasted. Dynamic Call Graph Useful for diagnosing overall performance problems. This diagram shows performance problem areas by color and size. Components (functions, classes [if you are analyzing a C++ program], or executables) that consume the most execution time will appear as large red rectangles. Components that are called excessively will have a red arc attached to them. Execution Density Useful for showing trends of program execution. This diagram displays trace data chronologically from top to bottom as thin horizontal lines of various colors in different columns. Statistics Useful for diagnosing overall performance problems. This diagram provides a textual report of execution time by component type: function, class (only if you are analyzing a C++ program), or executable. Components are sorted by execution time, with the component consuming the most time appearing at the top of the diagram by default. This diagram is also useful for determining which user functions to inline. Time Line Useful for diagnosing specific performance problems. For example, you might use this diagram to determine why a window takes a long time to paint. The Call Nesting diagram is useful in correlation with this diagram. For example, you can mark a point in time in this diagram, and then correlate it to the Call Nesting diagram. The correlated Call Nesting diagram shows you the function name associated with the time you marked in the Time Line diagram. ΓòÉΓòÉΓòÉ 9.1. Opening a Trace File in a Diagram ΓòÉΓòÉΓòÉ To open a trace file in any diagram, use any of the following methods: o 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. For step by step instructions, see Using the Analyze Trace Window. o 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 and click on OK. o Click mouse button 2 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. o From the Trace File menu of an open diagram, select Open as and then select a diagram from the cascaded menu. o From any open diagram, click the appropriate button in the toolbar. Note: If you open your trace file in a diagram and find that the file does not contain any trace events, your application may have been unable to locate CPPWPA3.DLL when you created the trace file. To correct this, change your path to point to the location of CPPWPA3.DLL (probably in the DLL subdirectory where you installed VisualAge for C++), and then recreate your trace file. Related Information o Using the Analyze Trace Window o Performance Analyzer - Window Manager Window o Analyze Trace Window o Trace File Pop-up Menu o Selecting Functions to Inline o Hints for Using the Performance Analyzer. ΓòÉΓòÉΓòÉ 9.1.1. Using the Analyze Trace Window ΓòÉΓòÉΓòÉ To select a trace file to analyze using the Analyze Trace window, complete the following steps: 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: o Call Nesting o Dynamic Call Graph o Execution Density o Statistics o Time Line. 4. Select OK. Related Information o Analyzing a Trace File o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistical Summary Diagram o Time Line Diagram o Creating a Trace File. ΓòÉΓòÉΓòÉ 9.2. Viewing Trace Files ΓòÉΓòÉΓòÉ The Performance Analyzer diagrams provide methods of making trace data easier to view and understand. The following topics describe some of these methods: o Using Filtering o Using Zooming o Using Scaling o Using Scrolling o Using Multiple Views o Recognizing Patterns o Understanding Correlation. ΓòÉΓòÉΓòÉ 9.2.1. Using Filtering ΓòÉΓòÉΓòÉ Filters allow you to temporarily reduce the amount of trace data displayed in a diagram. There are several techniques for filtering the trace file and isolating interesting or problematic areas. The following list contains filtering techniques that you can use in each of the diagrams: Call Nesting diagram In this diagram, you can filter data by: o Selecting specific functions and threads to view. The Performance Analyzer displays trace information for only those threads or functions selected. o Selecting a region of time to view. Dynamic Call Graph In this diagram, you can filter data by: o Selecting specific threads to view. The Performance Analyzer displays trace information for only those threads selected. o Displaying data by function, class, or executable. Using View >Nodes of, you can select which component (function, class, or executable) the diagram's nodes represent. o Scaling node sizes to change the size of the graphical representation of components (functions, classes [if you are analyzing a C++ program], or executables). Execution Density diagram In this diagram, you can filter data by: o Selecting specific functions and threads to view. The Performance Analyzer displays only those selected. o Scaling the diagram to reveal more information. o Selecting a region of time to view. Statistics diagram In this diagram, you can filter data by: o Selecting specific threads to view. The Performance Analyzer displays trace information for only those threads selected. o Displaying data by function, class, or executable. Using View >Details on, you can select which type of component data (function, class, or executable) is displayed in the diagram's Details pane. Time Line diagram In this diagram, you can filter data by: o Scaling the pages of the diagram to reveal more information. o Selecting a region of time to view. ΓòÉΓòÉΓòÉ 9.2.2. Using Zooming ΓòÉΓòÉΓòÉ The Dynamic Call Graph, Execution Density, and Time Line diagrams have zooming capabilities that allow you to enlarge (Zoom in) or reduce (Zoom out) the size of the diagram. Use Zoom in to focus on regions of a diagram that are of most interest. The Overview choice on the Dynamic Call Graph allows you to quickly move around in the diagram, and zoom in and out of the diagram. The gray box in the Overview window highlights the area currently displayed in the Dynamic Call Graph. o Click and hold mouse button 1 inside the gray box, and then move it around in the Overview window to quickly change the view in the Dynamic Call Graph. o Grab the sides of the gray box to resize the area shown in the Dynamic Call Graph. ΓòÉΓòÉΓòÉ 9.2.3. Using Scaling ΓòÉΓòÉΓòÉ Scaling is a way to change how much detail is displayed. You can view the diagram as a whole or magnify areas to see the finer detail. When details are hidden, you cannot spot patterns, anomalies, or features of the execution because there is too much information on the screen. The Execution Density and Time Line diagrams can be scaled along the time dimension. ΓòÉΓòÉΓòÉ 9.2.4. Using Scrolling ΓòÉΓòÉΓòÉ You can scroll the window in all diagrams to focus on areas of interest. You can also use correlation to scroll to areas of interest in each of the chronologically-scaled diagrams (Call Nesting, Execution Density, and Time Line). Correlation is described in Understanding Correlation. ΓòÉΓòÉΓòÉ 9.2.5. Using Multiple Views ΓòÉΓòÉΓòÉ The Performance Analyzer allows you to open a trace file in several diagrams or multiple views of the same diagram simultaneously. Sometimes opening two or more diagrams can help you better understand a program. 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 display and use the Dynamic Call Graph, Call Nesting, and Time Line diagrams to get a good understanding of the program's flow. After you have opened a diagram, one way you can open another diagram is by selecting the Open as choice from a Trace file menu, and then selecting another diagram from the cascaded menu. ΓòÉΓòÉΓòÉ 9.2.6. Recognizing Patterns ΓòÉΓòÉΓòÉ Program loops cause the same sequence of calls and returns to be repeated in the trace. The Performance Analyzer lets you combine like sequences in the Call Nesting diagram. By selecting Use pattern recognition, you can reduce the amount of screen space the diagram uses. Pattern recognition looks at a single thread and finds patterns of calls and returns. When this choice is enabled, the Call Nesting diagram groups these patterns using curved arcs. The number of repetitions is shown to the right. This technique shortens the number of pages which you must scroll through to look at your trace file. If you see a pattern repeated numerous times, you could group the functions in the pattern together with pragma alloc_text statements to improve performance by limiting the number of page swaps between calls in the patterns. Note: The Use pattern recognition check box (shown when you select View >Include threads...) is only selectable when you are filtering by threads. ΓòÉΓòÉΓòÉ 9.2.7. Understanding Correlation ΓòÉΓòÉΓòÉ Correlation allows you to mark a point in time in one diagram and then find that same point in another diagram. Using 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. 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. ΓòÉΓòÉΓòÉ 9.3. Understanding Overhead Time ΓòÉΓòÉΓòÉ When you compile and link your program, the compiler generates hooks (code added at the start and end of each function) that enable the Performance Analyzer to intercept trace events. The starting and ending times for each trace event are 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 execution 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. Note: 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, it should run at or near the same speed as the same program compiled without the profile hooks because trace events are not recorded. Related Information o Introducing the Performance Analyzer o Creating User Events in Your Program o Starting and Stopping the Performance Analyzer from Your Program o Tracing System Calls o Compiling and Linking Your Program o Starting the Performance Analyzer from a Command Line. o Starting the Performance Analyzer from WorkFrame o Performance Analyzer - Window Manager Window. ΓòÉΓòÉΓòÉ 9.4. 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 o Compiling and Linking Your Program o Statistics Diagram o IBM C/C++ Tools: Reference Summary o 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 IPERF.INI file. The IPERF.INI file stores your session settings. The default path name is the root operating system directory. If you want to store the IPERF.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 IPERF.INI file is created in the directory you specified. Related Information o Introducing the Performance Analyzer. o 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 o Menu Bar Summary - File - View - Options - Project (only available when working in the WorkFrame environment) - Help o Pop-up Menus - Executable - Trace file - Diagram o Push Buttons - Create Trace... - Analyze Trace.... Related Information o Introducing the Performance Analyzer o Compiling and Linking Your Program o Creating a Trace File o Using the Analyze Trace Window o Exiting the Performance Analyzer o 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 the Performance Analyzer Lets you end the Performance Analyzer application. Related Information o Compiling and Linking Your Program o Executable Pop-up Menu o Trace File Pop-up Menu o Diagram Pop-up Menu o Create Trace Window o Analyze Trace Window o Keys Help o Exiting the Performance Analyzer o Performance Analyzer - Window Manager Window o 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: o Clicking mouse button 2 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. o Clicking on the Create Trace... push button in the Performance Analyzer - Window Manager window. Related Information o Compiling and Linking Your Program o Create Trace Window o Creating a Customized Trace File o Performance Analyzer - Window Manager Window o 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: o Clicking mouse button 2 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. o Clicking on the Analyze Trace... push button in the Performance Analyzer - Window Manager window. Related Information o Compiling and Linking Your Program o Analyze Trace Window o Call Nesting Diagram o Dynamic Call Graph o Execution Density diagram o Statistics Diagram o Time Line Diagram o Performance Analyzer - Window Manager Window o 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 o Exiting the Performance Analyzer o Performance Analyzer - Window Manager Window o 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 between components 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 o Introducing the Performance Analyzer o Using the Analyze Trace Window o Performance Analyzer - Window Manager Window o Keys Help. ΓòÉΓòÉΓòÉ 11.2.1. Tree Lines Choice ΓòÉΓòÉΓòÉ Select the Tree lines choice to display directory tree lines between components to show relationships. 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 o Performance Analyzer - Window Manager Window o 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 diagram Execution Density diagram Statistics diagram Time Line diagram Related Information o Introducing the Performance Analyzer o Using the Analyze Trace Window o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Performance Analyzer - Window Manager Window o 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 o Introducing the Performance Analyzer o Using the Analyze Trace Window o Performance Analyzer - Window Manager Window o 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 Controls whether the Performance Analyzer provides a confirmation prompt upon exit. 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 o Introducing the Performance Analyzer o Using the Analyze Trace Window o Performance Analyzer - Window Manager Window o 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: Font entry field Type a font name in this entry field or click on the scroll bar to see a list of choices and select a name from the list. Font Style entry field Type a font style in this entry field or click on the scroll bar to see a list of choices and select a style from the list. Size entry field Type a font size in this entry field or click on the scroll bar to see a list of choices and select a size from the list. 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. 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 o Performance Analyzer - Window Manager Window o Keys Help. ΓòÉΓòÉΓòÉ 11.3.2. Quick Exit Choice ΓòÉΓòÉΓòÉ Select the Quick exit choice to control the way the Performance Analyzer ends. If this choice is enabled, (a check mark appears next to the choice when it's enabled) each time you exit the Performance Analyzer, the application will close immediately without a prompt confirming that you want to exit. This choice is available from the Options menu on the Performance Analyzer - Window Manager window. Related Information o Introducing the Performance Analyzer o Using the Analyze Trace Window o Performance Analyzer - Window Manager Window o 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 o Search Paths Window o Edit Source Choice o Performance Analyzer - Window Manager Window o Starting the Performance Analyzer from WorkFrame o 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: o OK o Cancel o 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 o Edit Source Choice o Performance Analyzer - Window Manager Window o Starting the Performance Analyzer from WorkFrame o 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 o Introducing the Performance Analyzer o Using the Analyze Trace Window o Performance Analyzer - Window Manager Window o 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 o Performance Analyzer - Window Manager Window o 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 IPERF.INI file. The saved settings remain active until the IPERF.INI file is erased. The Performance Analyzer will save the following on the Performance Analyzer - Window Manager window: o Font settings o Paths specified in Search paths window o Quick exit setting o Show icons setting o Tree lines setting o Unique trace file name setting o Window position o Window size To restore the default settings, select the Restore initial defaults Related Information o Restore Initial Defaults Choice o Performance Analyzer - Window Manager Window o 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 o Performance Analyzer - Window Manager Window o 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 o Trace Generation Window o Starting the Performance Analyzer from WorkFrame o 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. VisualAge for C++ Help Menu Items Launch the VisualAge for C++ documentation associated with the menu choice. These choices are available when you start the Performance Analyzer from WorkFrame. Product information Displays information about the Performance Analyzer. Related Information o Introducing the Performance Analyzer o Using the Analyze Trace Window o Performance Analyzer - Window Manager Window o 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 o Performance Analyzer - Window Manager Window o 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 o Performance Analyzer - Window Manager Window o 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 o Performance Analyzer - Window Manager Window o 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 o Performance Analyzer - Window Manager Window o Keys Help. ΓòÉΓòÉΓòÉ <hidden> VisualAge for C++ Help Menu Items ΓòÉΓòÉΓòÉ The central portion of the Help pull down menu is dedicated to all the online documentation that is shipped with VisualAge for C++. Making a selection from any of these Cascade menus launches the VisualAge for C++ documentation associated with the menu item. You can find the same documentation in the Information notebook found in the VisualAge for C++ Desktop folder. The Cascade menus are organized as follows: At A Glance Provides general information about VisualAge for C++, such as installing the product, a notebook that accesses the sample programs, and answers to frequently asked questions. Using VisualAge for 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 for C++. Use How Do I... information to find out how to perform common tasks within VisualAge for C++. C/C++ Provides access to the information that is specific to programming in C and C++. Class Libraries Provides access to the VisualAge for C++ Open Class Library documentation. Visual Programming > Provides access to the information that is specific to creating your programs visually. IPF, and Editing Provides access to the IPF and Editor references. SOM Provides access to the information specific to SOM. Windows Programming Provides access to information about programming with the Win32 Software Development Kit. ΓòÉΓòÉΓòÉ 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 o Performance Analyzer - Window Manager Window o 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 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 mouse button 2 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 o Introducing Performance Analyzer o Using the Analyze Trace Window o Exiting the Performance Analyzer o 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 o Compiling and Linking Your Program o Create Trace Window o Creating a Customized Trace File o Performance Analyzer - Window Manager Window o 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 o Exiting the Performance Analyzer o Performance Analyzer - Window Manager Window o 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 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 Closes all diagrams in which the trace file is displayed, and then 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 o Introducing the Performance Analyzer o Using the Analyze Trace Window o 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 o Performance Analyzer - Window Manager Window o 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 o Call Nesting Diagram o Performance Analyzer - Window Manager Window o 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 o 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 o Execution Density Diagram o Performance Analyzer - Window Manager Window o 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 o Statistics Diagram o Performance Analyzer - Window Manager Window o 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 o Time Line Diagram o Performance Analyzer - Window Manager Window o 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 o Exiting the Performance Analyzer o Performance Analyzer - Window Manager Window o 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 o Executable Pop-up Menu o Trace file Pop-up Menu o 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 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 o Introducing the Performance Analyzer o Show Icons Choice o Analyze Trace Window o Using the Analyze Trace Window o 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 o Executable Pop-up Menu o Trace file Pop-up Menu o 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 o Exiting the Performance Analyzer o Performance Analyzer - Window Manager Window o Keys Help. ΓòÉΓòÉΓòÉ 12. Create Trace Window ΓòÉΓòÉΓòÉ The Create Trace window lets you specify the name of the program that you want to trace. Optional fields allow you to enter parameters that you want to pass to your program, specify a custom trace file name, and attach a description to the trace file. You can display the Create Trace window from the Performance Analyzer - Window Manager window by: o Clicking on the Create Trace... push button o Selecting the Create trace... choice from the File menu. o Clicking mouse button 2 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 o Program Name: Entry Field o Optional Entry Fields - Program Parameters: - Trace File Name: - Trace File Description: o Push Buttons - Find... - OK - Cancel - Help. Related Information o Creating a Trace File o Performance Analyzer - Window Manager Window o Trace Generation Window o 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 o Creating a Trace File o Performance Analyzer - Window Manager Window o Trace Generation Window o 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 o Creating a Trace File o Performance Analyzer - Window Manager Window o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 12.3. Trace File Name Entry Field ΓòÉΓòÉΓòÉ Type the name of the 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 executable's directory unless you specify a path. Note: This entry field is optional. Related Information o Creating a Trace File o Creating a Customized Trace File o Unique trace file name o Performance Analyzer - Window Manager Window o Trace Generation Window o 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 o Creating a Trace File o Creating a Customized Trace File o Unique trace file name o Performance Analyzer - Window Manager Window o Trace Generation Window o 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: o Clicking on the Analyze Trace... push button o Selecting the Analyze trace... choice from the File menu. o Clicking mouse button 2 on a trace file name or icon (if displayed), and then selecting Analyze trace... from the pop-up menu. Note: If you open your trace file in a diagram and find that the file does not contain any trace events, your application may have been unable to locate CPPWPA3.DLL when you created the trace file. To correct this, change your path to point to the location of CPPWPA3.DLL (probably in the DLL subdirectory where you installed VisualAge for C++), and then recreate your trace file. Areas of the Analyze Trace Window o Trace File Name: Entry Field o Diagrams Check Boxes - Call Nesting - Dynamic Call Graph - Execution Density - Statistics - Time Line o Push Buttons - Find... - OK - Cancel - Help. Related Information o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Performance Analyzer - Window Manager Window o 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 (EXE) file, a dynamic load library (DLL) file, an object file, or a function. EXEs and DLLs 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 o Menu Bar Summary - Application - Edit - View - Options - Project (only available when working in the WorkFrame environment) - Help o Pop-up Menus - Executable - Object File - Function o Push Button - Trace. Related Information o Compiling and Linking Your Program o Creating a Trace File o Creating a Customized Trace File o 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 the Performance Analyzer Lets you end the Performance Analyzer application. Related Information o Trace Generation Window o 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 o Trace Generation Window o 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 o Exiting the Performance Analyzer o Trace Generation Window o 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 starts tracing when it reaches the triggered function and continues tracing until it receives a return from that function. If no triggers are set, the Performance Analyzer traces all enabled components. Remove trigger Removes a trigger on a function. This choice is available when you select a function that has a trigger set on it. Note: If triggers are set, the Performance Analyzer starts tracing when it reaches the triggered function and continues tracing until it receives a return from that function. If no triggers are set, the Performance Analyzer traces all enabled components. Related Information o Executable Pop-up Menu o Object File Pop-up Menu o Function Pop-up Menu o Trace Generation Window o 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 o Disable All Executables Choice o Executable Pop-up Menu o Object file Pop-up Menu o Function Pop-up Menu o Trace Generation Window o 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 o Enable All Executables Choice o Executable Pop-up Menu o Object file Pop-up Menu o Function Pop-up Menu o Trace Generation Window o 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: o Click on the file name or icon of the executable you want to enable. Then select Enable executable from the Edit menu. o Double-click on the file name or icon of the executable you want to enable. o Click mouse button 2 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: o Green (with no slash mark), the component is enabled. o Red (with a slash mark), the component is disabled. o White, the component cannot be traced. Related Information o Disable Executable Choice o Executable Pop-up Menu o Object file Pop-up Menu o Function Pop-up Menu o Trace Generation Window o 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: o Click on the file name or icon of the executable you want to disable. Then select Disable executable from the Edit menu. o Double-click on the file name or icon of the executable you want to enable. o Click mouse button 2 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: o Green (with no slash mark), the component is enabled. o Red (with a slash mark), the component is disabled. o White, the component cannot be traced. Related Information o Enable Executable Choice o Executable Pop-up Menu o Object file Pop-up Menu o Function Pop-up Menu o Trace Generation Window o 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: o Click on the file name or icon of the object file you want to enable. Then select Enable object file from the Edit menu. o Double-click on the file name or icon of the object file you want to enable. o Click mouse button 2 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: o Green (with no slash mark), the component is enabled. o Red (with a slash mark), the component is disabled. o White, the component cannot be traced. Related Information o Disable Object File Choice o Executable Pop-up Menu o Object file Pop-up Menu o Function Pop-up Menu o Trace Generation Window o 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: o Click on the file name or icon of the object file you want to disable. Then select Disable object file from the Edit menu. o Double-click on the file name or icon of the object file you want to disable. o Click mouse button 2 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: o Green (with no slash mark), the component is enabled. o Red (with a slash mark), the component is disabled. o White, the component cannot be traced. Related Information o Enable Object File Choice o Executable Pop-up Menu o Object file Pop-up Menu o Function Pop-up Menu o Trace Generation Window o 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: o Click on the name or icon of the function you want to enable. Then select Enable function from the Edit menu. o Double-click on the name or icon of the function you want to enable. o Click mouse button 2 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: o Green (with no slash mark), the component is enabled. o Red (with a slash mark), the component is disabled. o White, the component cannot be traced. Related Information o Disable Function Choice o Executable Pop-up Menu o Object file Pop-up Menu o Function Pop-up Menu o Trace Generation Window o 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: o Click on the name or icon of the function you want to disable. Then select Disable function from the Edit menu. o Double-click on the name or icon of the function you want to disable. o Click mouse button 2 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: o Green (with no slash mark), the component is enabled. o Red (with a slash mark), the component is disabled. o White, the component cannot be traced. Related Information o Enable Function Choice o Executable Pop-up Menu o Object file Pop-up Menu o Function Pop-up Menu o Trace Generation Window o 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. Note: If triggers are set, the Performance Analyzer starts tracing when it reaches the triggered function and continues tracing until it receives a return from that function. If no triggers are set, the Performance Analyzer traces all enabled components. Set a trigger in either of the following ways. On the Trace Generation window: 1. Select the function you want to trigger, and then select the Set trigger choice from the Edit menu. 2. Click mouse button 2 on the function you want to trigger (or the icon next to it), and then click on the Set trigger choice in the Function pop-up menu. The letter T appears in the icon next to the name of a triggered function. Related Information o Setting and Removing Triggers o Remove Trigger Choice o Function Pop-up Menu o Trace Generation Window o 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 starts tracing when it reaches the triggered function and continues tracing until it receives a return from that function. If no triggers are set, the Performance Analyzer traces all enabled components. Remove a trigger in either of the following ways. On the Trace Generation window: 1. Select a function on which a trigger has been set (the letter T appears in the icon next to its name in the Trace Generation window), and then select the Remove trigger choice from the Edit menu. 2. Select a function on which a trigger has been set by clicking mouse button2 on the function name (or the icon next to it), and then click on the Remove trigger choice in the Function pop-up menu. The T is removed from the icon next to the function name to indicate the trigger has been removed. Related Information o Setting and Removing Triggers o Set Trigger Choice o Function Pop-up Menu o Trace Generation Window o 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 components to show relationships. Related Information o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 14.3.1. Traceable Filter Choice ΓòÉΓòÉΓòÉ Select the Traceable filter choice to view only the components that are traceable. For a component to be traceable, it must have been properly compiled and linked, and it must be linked with CPPWPA3.OBJ. For instructions on compiling and linking your program, see Compiling and Linking Your Program. 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 o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 14.3.2. Tree Lines Choice ΓòÉΓòÉΓòÉ Select the Tree lines choice to display directory tree lines between components to show relationships. 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 o Trace Generation Window o 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 wrap Enable or disable buffer wrapping. Call depth... Select the call depth limit for each thread. 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 o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 14.4.1. Buffer Wrap Choice ΓòÉΓòÉΓòÉ Select the Buffer wrap choice to enable or disable buffer wrapping. This choice is available from the Options menu on the Trace Generation window. You can enable or disable buffer wrapping to choose when the data is written to the trace file. The default setting is disabled. A check mark appears next to the choice when it is enabled. The check mark does not appear when the choice is disabled. When Buffer wrap 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, the trace file is smaller, but some trace data is lost. When Buffer wrap is disabled, the data is written to the trace file every time the buffer fills. Related Information o Creating a Customized Trace File o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 14.4.2. Call Depth... Choice ΓòÉΓòÉΓòÉ Select the Call depth... choice to set the nesting depth (the number of functions that are on the call stack) 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 o Creating a Customized Trace File o Trace Generation Window o 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 either 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: o OK o Cancel o 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 o Creating a Customized Trace File o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 14.4.3. 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: Font entry field Type a font name in this entry field or click on the scroll bar to see a list of choices and select a name from the list. Font Style entry field Type a font style in this entry field or click on the scroll bar to see a list of choices and select a style from the list. Size entry field Type a font size in this entry field or click on the scroll bar to see a list of choices and select a size from the list. 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. 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 o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 14.4.4. 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 o Creating a Customized Trace File o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 14.4.4.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: o OK o Cancel o Help. Related Information o Resolve Name Conflict Window o Unique Trace File Name Choice o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 14.4.5. 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 o Creating a Customized Trace File o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 14.4.5.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: o OK o Cancel o 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 o Analyze Trace Window o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 14.4.6. 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: o Select the Trace Generation window Options menu. o 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: o Select the Trace Generation window Options menu. o 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 o Creating a Customized Trace File o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 14.4.7. 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 o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 14.4.7.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 IPERF.INI file. The saved settings remain active until the IPERF.INI file is erased. The Performance Analyzer will save the following settings on the Trace Generation window: o Buffer wrap o Font o Call depth o Time stamp events o Timeout control o Traceable filter o Tree lines o Window position o Window size To restore the default settings, select the Restore Initial Defaults Related Information o Restore Initial Defaults Choice o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 14.4.7.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 o Trace Generation Window o 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 o Edit Source Choice o Search Paths Window o Trace Generation Window o Starting the Performance Analyzer from WorkFrame o 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: o An object file, the source is opened to the first line of the file. o 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 o Locate Executable Window o Locate Source File Window o Search Paths Window o Trace Generation Window o Starting the Performance Analyzer from WorkFrame o 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. VisualAge for C++ Help Menu Items Launch the VisualAge for C++ documentation associated with the menu choice. These choices are available when you start the Performance Analyzer from WorkFrame. Product information Displays information about the Performance Analyzer. Related Information o Trace Generation Window o 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 o Trace Generation Window o 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 o Trace Generation Window o 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 o Trace Generation Window o 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 o Trace Generation Window o 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 o Trace Generation Window o 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 2 on the file name or icon of an executable (EXE) or a dynamic link library (DLL) file to display the Executable pop-up menu. (If you click on the file name of a component other than an executable, the pop-up menu you see will be different.) 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 o Introducing the Performance Analyzer o Edit Menu o Trace Generation Window o 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 2 on the file name of an object file (or the plus or minus icon next to it) to display the Object File pop-up menu. (If you click on the file name of a component other than an executable, the pop-up menu you see will be different.) 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 o Edit Menu o Edit Source Choice o Project Menu o Trace Generation Window o Starting the Performance Analyzer from WorkFrame o 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 2 on the name of a function (or the plus or minus icon next to it) to display the Function pop-up menu. (If you click on the file name of a component other than an executable, the pop-up menu you see will be different.) 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. 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 o Edit Menu o Edit Source Choice o Project Menu o Trace Generation Window o Starting the Performance Analyzer from WorkFrame o 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: o OK o Cancel o 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 o Edit Source Choice o Locate Source File Window o Search Paths Window o Trace Generation Window o Starting the Performance Analyzer from WorkFrame o 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: o OK o Cancel o 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 o Edit Source Choice o Locate Executable Window o Search Paths Window o Trace Generation Window o Starting the Performance Analyzer from WorkFrame o 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: o 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. o 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. o 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 o Status Area o Push Buttons - Stop - Trace on - Trace off. Note: The Help push button displays this Help information. Related Information o Using the Analyze Trace Window o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 15.1. Status Area ΓòÉΓòÉΓòÉ The following information is displayed in the Status Area on the Application Monitor window: o Name of the program being traced o Name of the trace file o Number of bytes written to the trace file o Number of events written to the trace file Related Information o Trace Off Push Button o Trace On Push Button o Using the Analyze Trace Window o Trace Generation Window o Keys Help. ΓòÉΓòÉΓòÉ 16. 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, program crashes, and thread delays. 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. (User events and annotations are text strings in the diagram.) 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 o Menu Bar The following choices are available from the Call Nesting diagram menu bar: - Trace file - Edit - View - Options - Project - Help o Status Area The Status Area provides information about the following: - Trace description - Filters o Call Nesting Pop-up Menus - Call Nesting Diagram Pop-up Menu - Call Nesting Selected Item Pop-up Menu Related Information o Analyze Trace Window o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 the Performance Analyzer Exits the Performance Analyzer. Related Information o Analyze Trace Window o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o 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 o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o 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 o Open As Choice o 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 o Open As Choice o 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 o Open As Choice o 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 o Open As Choice o 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 o Open As Choice o 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. o OK o Font... o Job properties... o Cancel o Help Related Information o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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. Depending on your printer, you may be able to select the following: o Orientation o Form Configuration o Select Form Source o Select Form o Default Font o Resolution o Performance Options From the Printer Settings window, select the appropriate push button. Related Information o 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 o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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 o Keys Help. ΓòÉΓòÉΓòÉ 16.1.4. Window Manager Choice ΓòÉΓòÉΓòÉ Select the Window Manager choice to display the Window Manager window. Related Information o Performance Analyzer - Window Manager o Keys Help. ΓòÉΓòÉΓòÉ 16.1.5. Exit the Performance Analyzer Choice ΓòÉΓòÉΓòÉ Select the Exit the Performance Analyzer choice from the Trace file menu to exit the application. Related Information o 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 range. Select all Select the entire Call Nesting diagram. Related Information o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o 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... Locates the text of function calls and returns. User event... Locates user events. Annotation... Locates annotated text. Related Information o Keys Help. ΓòÉΓòÉΓòÉ 16.2.1.1. Function Choice ΓòÉΓòÉΓòÉ Select the Function... choice to search for function calls and returns. When you select the Function... choice, the Find Function window appears. Related Information o 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. 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. Enter the function file name in the Find entry field. If you don't know the function file name, you can use wildcard characters (* and ?) in the entry field, as follows: o Use an asterisk (*) to represent 0 or more arbitrary characters. For example, enter: - * to display a list of all function file names. - b* to display all function file names, regardless of length, that begin with the letter b. - *b to display all function file names that end with the letter b. o Use a question mark (?) to represent a single arbitrary character. For example, enter ?b* to display all function file names that start with any character and have the letter b as their second character. Note: Wildcards are especially useful when you are searching for a fully qualified C++ function name (for example, myClass::function[parameter] ). 4. Click on the Case sensitive check box if you want to enable case sensitive searching. 5. Click on the OK push button. 6. Click on the name of a function in the list box. 7. Select the thread that you want searched. 8. Click on the appropriate radio button to search for occurrences of when the function was: o Called o Returned o Either called or returned. 9. Select the appropriate push button to continue: o OK o Cancel o Help. Note: The function is highlighted when found. Related Information o Call Nesting Diagram o Find Annotation Window o Find User Event Window o 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 o Keys Help. ΓòÉΓòÉΓòÉ <hidden> Find User Event Window ΓòÉΓòÉΓòÉ Use the Find User Event... window to search for a specific user event. Note: This choice is only available when there are user events in the trace file. Find User Event... To search for a user event : 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. 2. Select User event... from the cascaded menu, and the Find User Event dialog appears. 3. Use the Find entry field and the Case sensitive check box 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 entry field. 4. Select a user event from the list box. 5. Select the appropriate push button to continue: o OK o Cancel o Help. Note: The user event is highlighted when found. Related Information o Call Nesting Diagram o Defining User Events and Creating Prototypes o Find Function Window o Find Annotation Window o 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 o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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 entry field. 4. Select an annotation from the list box. 5. Select the appropriate push button to continue: o OK o Cancel o Help Note: The annotated comment is highlighted when found. Related Information o Call Nesting Diagram o Find Function Window o Find User Event Window o 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 o Call Nesting Diagram Pop-up Menu o Find Function Window o Find User Event Window o Find Annotation Window o 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 o Call Nesting Selected Item Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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: o Add/Change o Remove o Cancel o 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 o Find Annotation Window o Defining User Events o Call Nesting Selected Item Pop-up Menu o 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 o 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: o Seconds (s) o Milliseconds (ms) o Microseconds (us) 2. Use the spin buttons to select the time you want to display. 3. Select the appropriate push button to continue: o OK o Cancel o Help. Related Information o Select Time Range Window o 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 o 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: o seconds (s), o milliseconds (ms), o 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: o seconds (s), o milliseconds (ms), o microseconds (us). 5. Select the appropriate push button to continue: o OK o Cancel o Help. Related Information o 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 o 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 which functions are included in the diagram. Each selected function and any functions in its call chain will be shown. Include threads.... Controls which threads are included in the diagram and lets you select Pattern Recognition. Related Information o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o 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 o Call Nesting Diagram Pop-up Menu o 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. Each selected function and any functions in its call chain will be shown. 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: o OK o Cancel o 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: o OK o Cancel o 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: o OK o Cancel o Help Related Information o Call Nesting Diagram Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ 16.3.2. Include Threads... Choice ΓòÉΓòÉΓòÉ Select the Include threads... choice to select which threads are displayed in the diagram and to select Pattern Recognition. 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 o Call Nesting Diagram Pop-up Menu o 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. Select Options > Color... to see the range of execution times represented by the colors of the lines in the diagram. You can also enable Use 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 is on the right. Note: Use pattern recognition can only be enabled when a single thread pattern is displayed. When Use 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: o OK o Cancel o 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: o OK o Cancel o Help. Selecting All Threads To select all threads: 1. Highlight All threads to select all threads. 2. Select the appropriate push button to continue: o OK o Cancel o Help Related Information o Call Nesting Diagram Pop-up Menu o 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 original settings. Related Information o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Call Nesting Diagram Pop-up Menu o Call Nesting Selected Item Pop-up Menu o 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 o Call Nesting Selected Item Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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 with 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: o OK o Help. Related Information o Call Nesting Diagram o Call Nesting Selected Item Pop-up Menu o 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 o Call Nesting Selected Item Pop-up Menu o 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 Font window appears. The Font window has the following areas: Font entry field Type a font name in this entry field or click on the scroll bar to see a list of choices and select a name from the list. Font Style entry field Type a font style in this entry field or click on the scroll bar to see a list of choices and select a style from the list. Size entry field Type a font size in this entry field or click on the scroll bar to see a list of choices and select a size from the list. 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. Cancel push button Closes the window without making changes. Related Information o Call Nesting Diagram Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ <hidden> Correlation Window ΓòÉΓòÉΓòÉ Use the Correlation window to mark a point in time 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 1 on the first event. b) While holding mouse button 1, 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: o OK o Select all o Deselect all o Cancel o Help. When you select the OK push button, the Performance Analyzer highlights correlated points in the selected diagrams. Related Information o Zoom In Choice o Zoom Out Choice o Call Nesting Diagram o Call Nesting Diagram Pop-up Menu o Execution Density Diagram o Time Line Diagram o 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 o Call Nesting Diagram Pop-up Menu o 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. 2. Select the check box to draw separator lines between the threads. A check mark 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: o OK o Apply o Cancel o Help. Related Information o Call Nesting Diagram o Time Line Diagram o Call Nesting Diagram Pop-up Menu o 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 what appears in 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 o Keys Help. ΓòÉΓòÉΓòÉ <hidden> Call Nesting 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 Call Nesting Status Area window include: o Trace Description o Filters Select the appropriate check box to continue. Related Information o Dynamic Call Graph Status Area Window o Execution Density Status Area Window o Status Area Window o 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 Hover help. The choices from the Tool bar cascaded menu are: Show Choose to either show or hide the tool bar. Hover help Choose to either enable or disable displaying the help text when the mouse pointer hovers over the tool bar buttons. Related Information o 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 o Tool Bar Hover Help Choice o Keys Help. ΓòÉΓòÉΓòÉ 16.4.6.2. Tool Bar Hover Help Choice ΓòÉΓòÉΓòÉ Select the Hover help 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 help choice is enabled, a check mark will appear beside the choice. Select the Hover help choice again to remove the check mark and the Hover help choice will be disabled. Related Information o Tool Bar Show Choice o 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 Saves the current session settings. Restore initial defaults Restores the original settings. Related Information o Save Choice o Restore Initial Defaults Choice o Keys Help. ΓòÉΓòÉΓòÉ 16.4.7.1. Save Choice ΓòÉΓòÉΓòÉ Select the Save choice to save the current settings. These settings are stored in the IPERF.INI file and remain active until that file is erased. To restore the default settings, select the Restore defaults choice. Related Information o Restore Initial Defaults Choice o 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 o Save Choice o 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 o Search Paths Window o Trace Generation Window o 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 o Locate Executable Window o Locate Source File Window o Search Paths Window o Starting the Performance Analyzer from WorkFrame o 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. VisualAge for C++ Help Menu Items Launch the VisualAge for C++ documentation associated with the menu choice. These choices are available when you start the Performance Analyzer from WorkFrame. Product information Displays information about the Performance Analyzer. Related Information o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 what appears in 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 o Dynamic Call Graph Status Area o Execution Density Status Area o Time Line Status Area o 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 2 on the background area of the diagram. The menu is displayed with the following choices: o Find > o Find next o Include functions... o Include threads... o Font... o Thread layout... Related Information o Call Nesting Selected Item Pop-up Menu o 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 2 on the highlighted area of the diagram. The menu is displayed with the following choices: o Annotate... o Call stack... o Correlation... o Edit function Related Information o Call Nesting Diagram Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ 17. Dynamic Call Graph ΓòÉΓòÉΓòÉ The Dynamic Call Graph is a graphical representation of your program's execution. Use this diagram to: o Get an overall view of your program and its flow. o See the relative importance (in terms of execution time) of program components. o See where time is spent in your program. o See your program's call hierarchy. Note: The Dynamic Call Graph is not an inheritance diagram. In this diagram, nodes represent components. Components can be functions, classes (only if you are analyzing a C++ program), or executables. Arcs, which are displayed between pairs of nodes, represent calls from one component to another. Only calls made during the given execution of the program are displayed. The diagram's color code helps you quickly determine where time is spent in your program and estimate the relative number of calls that occur between functions, classes, or executables. Additionally, the diagram uses node size to show you information about execution time and time on stack. For more information about the diagram's use of color and node size, see Dynamic Call Graph Nodes and Arcs. To choose which type of component the nodes represent, select View > Nodes of, and then select one of the following choices: o Functions. o Classes. (You can only select this choice if you are analyzing a C++ program.) o Executables. By default, the Nodes of setting is Functions for C programs and Classes for C++ programs. Using the Nodes of choice to filter the diagram by function, class, or executable allows you to show the amount of detail that is meaningful to you. For example, you may want to view classes instead of functions in order to discern patterns or find problem areas more easily. The Status Area displays the trace file description (if it has one), the type of component information displayed (function, class, or executable), and information about the selected node or arc. Areas of the Dynamic Call Graph Window o Menu Bar The following choices are available from the Dynamic Call Graph menu bar: - Trace file - View - Options - Project - Help. o Status Area The Status Area provides information about the following: - Trace description - Filters - Selected object. - Dynamic Call Graph Pop-up Menus -- Dynamic Call Graph Selected Arc Pop-up Menu -- Dynamic Call Graph Node Pop-up Menu Related Information o Dynamic Call Graph Nodes and Arcs o Call Nesting Diagram o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o Keys Help. ΓòÉΓòÉΓòÉ 17.1. Dynamic Call Graph Nodes and Arcs ΓòÉΓòÉΓòÉ The Dynamic Call Graph uses nodes to represent program components (functions, classes [only if you are analyzing a C++ program], or executables) and arcs to represent calls between components. Color and node size have special significance in this diagram. Node color and arc color depict the time spent in the node and the number of calls between nodes, respectively. Node size for a function is based on the function's execution time and time on stack as they compare to the function or functions with the greatest execution time and time on stack. Node size for an executable or a class is based on execution time. When a node is selected, it is surrounded by a green box. When an arc is selected, it is green. Displaying Information about Nodes and Arcs To display: o The name of the component a node represents, click on the node to select it. (When selected, a node is surrounded by a box.) The name of the component represented appears in the Status Area. o Detailed information about the component a node represents, do either of the following: - Double-click on the node. - Click mouse button 2 on the node, and then select Display information... from the pop-up menu. The pop-up window displayed using either of these methods identifies the component represented and reports other useful statistics, including execution time, number of calls, and time on the stack. For classes, member function information is also displayed. o The names of the components involved in a call, click on the arc representing the call to select it. (When selected, an arc is green.) The names of the components represented (the caller and callee) appear in the Status Area. o Detailed information about the components involved in a call, do either of the following: - Double-click on the arc. - Click mouse button 2 on the arc, and then select Display information... from the pop-up menu. The pop-up window displayed using either of these methods identifies the caller, the callee, the number of times the caller called the callee, and the total number of times the callee was called during the program execution. Node and Arc Color Node color is based on the maximum execution time spent in any component. Arc color is based on the maximum number of calls between any two pairs of components. The following table explains how the Dynamic Call Graph uses node color. Note: Class execution time is calculated by totalling the execution times for all member functions contained in the class. +--------------------------------------------------------+ |Node Color: |Indicates: | |---------------+----------------------------------------| |---------------+----------------------------------------| |Gray |Less than 1/8 of the maximum execution | | |time was spent in the component. | |---------------+----------------------------------------| |Blue |Between 1/8 and 1/4 of the maximum | | |execution time was spent in the | | |component. | |---------------+----------------------------------------| |Yellow |Between 1/4 and 1/2 of the maximum | | |execution time was spent in the | | |component. | |---------------+----------------------------------------| |Red |Greater than 1/2 of the maximum | | |execution time was spent in the | | |component. | +--------------------------------------------------------+ The following table explains how the Dynamic Call Graph uses arc color: +--------------------------------------------------------+ |Arc Color: |Indicates: | |---------------+----------------------------------------| |Green |An arc is selected. | |---------------+----------------------------------------| |Gray |Less than 1/8 of the maximum number of | | |calls made were made between components.| |---------------+----------------------------------------| |Blue |1/8 to 1/4 of the maximum number of | | |calls made were made between components.| |---------------+----------------------------------------| |Yellow |1/4 to 1/2 of the maximum number of | | |calls made were made between components.| |---------------+----------------------------------------| |Red |At least 1/2 of the maximum number of | | |calls made were made between components.| +--------------------------------------------------------+ Node Size For functions, node height is determined by the node's execution time relative to the function that has the greatest execution time. Node width is determined by the node's time on stack relative to the function that has the greatest time on stack. Time on stack is the time spent on the call stack. If a function is waiting for a message, the time spent waiting is logged as time on stack. Note: Time on stack includes all time spent in subroutines. For executables and classes, node height and width are based on execution time; therefore, the nodes representing these components will always be square. Time on stack is not relevant for executables and classes. Related Information o Dynamic Call Graph Function Information Window o Dynamic Call Graph Class Information Window o Dynamic Call Graph Executable Information Window o Dynamic Call Graph o Dynamic Call Graph Status Area o 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 window. Exit the Performance Analyzer Exits the Performance Analyzer. Related Information o Analyze Trace Window o Call Nesting Diagram o Execution Density Diagram o Statistics Diagram o Time Line Diagram o 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 o Using the Analyze Trace Window o 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 o Open As Choice o 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 o Open As Choice o 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 o Open As Choice o 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 o Open As Choice o 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 o Open As Choice o 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. o OK o Font... o Job properties... o Cancel o Help Related Information o 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 o Keys Help. ΓòÉΓòÉΓòÉ 17.2.4. Window Manager Choice ΓòÉΓòÉΓòÉ Select the Window Manager choice to display the Window Manager window. Related Information o Performance Analyzer - Window Manager o Keys Help. ΓòÉΓòÉΓòÉ 17.2.5. Exit the Performance Analyzer Choice ΓòÉΓòÉΓòÉ Select Exit the Performance Analyzer to close Performance Analyzer and all windows. Related Information o Keys Help. ΓòÉΓòÉΓòÉ 17.3. Dynamic Call Graph View Menu ΓòÉΓòÉΓòÉ The following choices are available from the View menu: Nodes of > Lets you choose whether the diagram's nodes represent functions, classes (only if you are analyzing a C++ program) or executables. Include threads... Controls which threads are included in the diagram. Show arcs Displays or hides all arcs 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 graph Sizes the diagram to fit in the window. Restore graph Restores nodes and arcs to the diagram to show the default view. Related Information o Call Nesting Diagram o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Keys Help. ΓòÉΓòÉΓòÉ 17.3.1. Nodes of Cascading Choice ΓòÉΓòÉΓòÉ Select the Nodes of choice to choose which type of component the diagram's nodes represent. This choice is available from the View menu on the Dynamic Call Graph. Nodes can represent functions, classes (only if you are analyzing a C++ program), or executables. For C programs, the default setting for Nodes of is Functions. For C++ programs, the default setting for Nodes of is Classes. In the Dynamic Call Graph diagram, you can access this choice by selecting View >Nodes of, and then selecting one of the following choices: o Functions. o Classes. (You can only select this choice if you are analyzing a C++ program.) o Executables. By using these choices to group program components, you can show the amount of detail that is meaningful to you. For example, you may want to view classes instead of functions in order to discern patterns or find problem areas more easily. Related Information o Keys Help. ΓòÉΓòÉΓòÉ 17.3.1.1. Functions Choice ΓòÉΓòÉΓòÉ Select the Functions choice to specify that nodes in the Dynamic Call Graph represent functions. You can access this choice by selecting View > Nodes of > Functions. A check mark is displayed next to the choice when it is selected. Related Information o Classes Choice o Executables Choice o Keys Help. ΓòÉΓòÉΓòÉ 17.3.1.2. Classes Choice ΓòÉΓòÉΓòÉ Select the Classes choice to specify that nodes in the Dynamic Call Graph represent classes. As a class, each node represents the data for every member function contained in that class. You can access this choice by selecting View > Nodes of > Classes. A check mark is displayed next to the choice when it is selected. Related Information o Functions Choice o Executables Choice o Keys Help. ΓòÉΓòÉΓòÉ 17.3.1.3. Executables Choice ΓòÉΓòÉΓòÉ Select the Executables choice to specify that nodes in the Dynamic Call Graph represent executables. As an executable, each node represents the data for every function contained in that executable. You can access this choice by selecting View > Nodes of > Executables. A check mark is displayed next to the choice when it is selected. Related Information o Functions Choice o Classes Choice o Keys Help. ΓòÉΓòÉΓòÉ 17.3.2. Include Threads... Choice ΓòÉΓòÉΓòÉ Select the Include threads... choice to select which threads are displayed in the diagram. This choice is available from the View menu on the Dynamic Call Graph. Use the Include threads... choice to filter the trace file, which allows you to isolate specific areas of interest or areas where problems occur. When you select this choice, an Include Threads window appears. Related Information o Keys Help. ΓòÉΓòÉΓòÉ 17.3.2.1. Include Threads Window ΓòÉΓòÉΓòÉ Use the Include Threads window to select or isolate specific threads in the Dynamic Call Graph. This choice is available from the View menu on 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 of execution time represented by the size and color of nodes are based upon the total execution time of the selected threads, not the total execution time. When you change 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: o OK o Select all o Deselect all o Cancel o Help. Selecting All Threads To select all threads: 1. Highlight All threads to select all threads. 2. Select the appropriate push button to continue: o OK o Select all o Deselect all o Cancel o Help Related Information o Dynamic Call Graph o Execution Density Diagram o Analyze Trace Window o Keys Help. ΓòÉΓòÉΓòÉ <hidden> Show Arcs Choice ΓòÉΓòÉΓòÉ Select the Show arcs choice to display or hide all arcs in the diagram. The default setting is to display arcs. To make it easier to select nodes on a busy graph, you can hide arcs by selecting this choice and disabling it. The check mark next to Show arcs is removed when the choice is disabled. Select this choice from the View menu on the Dynamic Call Graph. Note: If the Who Calls Whom or Who Calls Me push button is selected, arcs to or from the selected node will not be displayed if Show arcs is disabled. Related Information o Keys Help. ΓòÉΓòÉΓòÉ 17.3.3. Overview Choice ΓòÉΓòÉΓòÉ Select the Overview choice to display a scaled-down image of the diagram you are viewing. This choice is available from the View menu on the Dynamic Call Graph. 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 1 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 1, the main window is redrawn to reflect the new view. 2. View a different area of the diagram. Press and hold mouse button 1 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 1, the main window is redrawn to reflect the new view. Related Information o Dynamic Call Graph o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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. This window is displayed when you select View > Overview on the Dynamic Call Graph. Switching Views To view a larger or smaller area of the Dynamic Call Graph: Press and hold mouse button 1 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 1, the main window is redrawn to reflect the new view. View a Different Area of the Graph Press and hold mouse button 1 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 1, the main window is redrawn to reflect the new view. Related Information o Dynamic Call Graph o Analyze Trace Window. o Keys Help. ΓòÉΓòÉΓòÉ 17.3.4. 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. This choice is available from the View menu on the Dynamic Call Graph. 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 you can press the +key on the numeric key pad or Shift and the + key on the keyboard. Each time you zoom in using the Zoom in menu choice or the keyboard keys, the window appears larger. To return the diagram to the original size, use the Re-lay graph choice in the View menu. Related Information o Zoom Bar o Zoom Out Choice o Keys Help. ΓòÉΓòÉΓòÉ 17.3.5. 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. This choice is available from the View menu on the Dynamic Call Graph. The original default view is the smallest size in which the graph can be displayed. To decrease the view of the diagram, select Zoom out from the View menu, or you can press the minus key (-) on the numeric key pad or Shift and the - key on the keyboard. Each time you zoom out using the Zoom out menu choice or the keyboard keys, the window appears smaller. To return the diagram to the original size, use the Re-lay graph choice in the View menu. Related Information o Zoom Bar o Zoom In Choice o Keys Help. ΓòÉΓòÉΓòÉ 17.3.6. Re-lay Graph Choice ΓòÉΓòÉΓòÉ Select the Re-lay graph choice to center and resize the nodes. This choice is available from the View menu on the Dynamic Call Graph. See Dynamic Call Graph for more information about isolating nodes and arcs. To re-lay the diagram, select Re-lay graph from the View menu. The diagram is centered in the window with all selected elements sized to fit. Related Information o Zoom Bar o Restore Choice o Keys Help. ΓòÉΓòÉΓòÉ 17.3.7. Restore Graph Choice ΓòÉΓòÉΓòÉ Select the Restore graph choice to return the diagram to the default view. This choice is available from the View menu on the Dynamic Call Graph. To restore a diagram, select Restore graph 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 o Zoom Bar o Re-lay Graph Choice o 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... Searches for functions, classes (only if you are analyzing a C++ program), or executables in the diagram. Status area... Area at the top of the window that 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 o Call Nesting Diagram o Execution Density Diagram o Statistics Diagram o Time Line Diagram o 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 nodes and arcs are then displayed in proportion to the execution time and time on stack. To disable the Scale node size function, click on it again to remove the check mark Related Information o Analyze Trace Window o Execution Density Diagram Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ 17.4.2. Find... Choice ΓòÉΓòÉΓòÉ Select the Find... choice to search for functions, classes (only if you are analyzing a C++ program), or executables in the Dynamic Call Graph diagram. When you select the Find... choice, a Find window appears. The Find window that is displayed depends on what type of component (function, class, or executable) you are searching for. If you are searching for: o A function, the Find Function window appears. o A class, the Find Class window appears. o An executable, the Find Executable window appears. Before you select the Find... choice, choose the type of component you want to search for by selecting View > Nodes of, and then selecting Functions, Classes, or Executables. Related Information o Find Function Window o Find Class Window o Find Executable Window o Keys Help. ΓòÉΓòÉΓòÉ <hidden> Find Function Window ΓòÉΓòÉΓòÉ Use the Find Function window to search for a specific function in the diagram. To search for a function: 1. Make sure the View > Nodes of choice (if you are searching in the Dynamic Call Graph diagram) or the View > Details on choice (if you are searching in the Statistics diagram) is set to Functions. 2. Select Options > Find.... The Find Function window appears. 3. Enter the function name in the Find entry field. If you don't know the function name, you can use wildcard characters (* and ?) in the entry field, as follows: o Use an asterisk (*) to represent 0 or more arbitrary characters. For example, enter: - * to display a list of all function names. - b* to display all function names, regardless of length, that begin with the letter b. - *b to display all function names that end with the letter b. o Use a question mark (?) to represent a single arbitrary character. For example, enter ?b* to display all function names that start with any character and have the letter b as their second character. Note: Wildcards are especially useful when you are searching for a fully qualified C++ function name (for example, myClass:: function[parameter] ). 4. Click on the Case sensitive check box if you want to enable case sensitive searching. 5. Click on the OK push button. 6. Click on the name of a function in the list box. 7. Select the appropriate push button to continue: o OK o Cancel o Help. Note: The function is highlighted when found. Related Information o Find Class Window o Find Executable Window o Keys Help. ΓòÉΓòÉΓòÉ <hidden> Find Class Window ΓòÉΓòÉΓòÉ Use the Find Class window to search for a specific class in the diagram. To search for a class: 1. Make sure the View > Nodes of choice (if you are searching in the Dynamic Call Graph diagram) or the View > Details on choice (if you are searching in the Statistics diagram) is set to Classes. 2. Select Options > Find.... The Find Class window appears. 3. Enter the class name in the Find entry field. If you don't know the class name, you can use wildcard characters (* and ?) in the entry field, as follows: o Use an asterisk (*) to represent 0 or more arbitrary characters. For example, enter: - * to display a list of all class names. - b* to display all class names, regardless of length, that begin with the letter b. - *b to display all class names that end with the letter b. o Use a question mark (?) to represent a single arbitrary character. For example, enter ?b* to display all class names that start with any character and have the letter b as their second character. 4. Click on the Case sensitive check box if you want to enable case sensitive searching. 5. Click on the OK push button. 6. Click on the name of a class in the list box. 7. Select the appropriate push button to continue: o OK o Cancel o Help. Note: The class is highlighted when found. Related Information o Find Function Window o Find Executable Window o Keys Help. ΓòÉΓòÉΓòÉ <hidden> Find Executable Window ΓòÉΓòÉΓòÉ Use the Find Executable window to search for a specific executable in the diagram. To search for an executable: 1. Make sure the View > Nodes of choice (if you are searching in the Dynamic Call Graph diagram) or the View > Details on choice (if you are searching in the Statistics diagram) is set to Executables. 2. Select Options > Find.... The Find Executable window appears. 3. Enter the executable file name in the Find entry field. If you don't know the executable file name, you can use wildcard characters (* and ?) in the entry field, as follows: o Use an asterisk (*) to represent 0 or more arbitrary characters. For example, enter: - * to display a list of all executable file names. - b* to display all executable file names, regardless of length, that begin with the letter b. - *b to display all executable file names that end with the letter b. o Use a question mark (?) to represent a single arbitrary character. For example, enter ?b* to display all executable file names that start with any character and have the letter b as their second character. 4. Click on the Case sensitive check box if you want to enable case sensitive searching. 5. Click on the OK push button. 6. Click on the name of an executable in the list box. 7. Select the appropriate push button to continue: o OK o Cancel o Help. Note: The executable is highlighted when found. Related Information o Find Function Window o Find Class Window o Keys Help. ΓòÉΓòÉΓòÉ 17.4.3. Status Area... Choice ΓòÉΓòÉΓòÉ Select the Status area... choice to change what appears in the area at the top of the Dynamic Call Graph window. The Status area includes: o Trace description o Filters o Selected object When you select Status area, the Status Area window appears. Related Information o Keys Help. ΓòÉΓòÉΓòÉ <hidden> Dynamic Call Graph 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 Dynamic Call Graph Status Area window include: o Trace description o Filters o Selected object Select the appropriate check box to continue. Related Information o Call Nesting Status Area Window o Execution Density Status Area Window o Status Area Window. o 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 help Choose to either enable or disable displaying the help text when the mouse pointer hovers over the tool bar buttons. Related Information o 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 Saves the current session settings. Restore initial defaults Restores the original settings. Related Information o Save Choice o Restore Initial Defaults Choice o Keys Help. ΓòÉΓòÉΓòÉ 17.4.5.1. Save Choice ΓòÉΓòÉΓòÉ Select the Save choice to save the current settings. These settings are stored in the IPERF.INI file and remain active until that file is erased. To restore the default settings, select the Restore initial defaults choice. Related Information o Restore Initial Defaults Choice o 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 o Save Choice o 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 o Search Paths Window o Trace Generation Window o 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 o Locate Executable Window o Locate Source File Window o Search Paths Window o Starting the Performance Analyzer from WorkFrame o 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. VisualAge for C++ Help Menu Items Launch the VisualAge for C++ documentation associated with the menu choice. These choices are available when you start the Performance Analyzer from WorkFrame. Product information Displays information about the Performance Analyzer. Related Information o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 from the Options menu to change what appears in 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 to display the trace file description that was entered when the file was created. If a description was not attached to the trace file, this field is empty. Filters Select to display the filter set with View > Nodes of. Selected object Select to display information about the selected node or arc. Note: If you highlight a node, the name of the component it represents is displayed. If you highlight an arc, the names of the components involved in the call are displayed. Related Information o Call Nesting Status Area o Execution Density Status Area o Time Line Status Area o 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: o Zoom in choice from the View menu to change the scale of the diagram view. When zooming in, your view is a step closer to the selected object and the object in the window appears larger. o 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. o Zoom bar in the Dynamic Call Graph window by sliding the arm up or down, to change the diagram view. o Re-lay graph choice from the View menu to return to the original diagram view. o Overview choice from the View menu to quickly move around in the viewing area of the diagram. 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 Selected Arc Pop-up Menu ΓòÉΓòÉΓòÉ The pop-up menus allow you to quickly access features that are frequently used. The Dynamic Call Graph Selected Arc Pop-up Menu contains actions that can be applied to a selected arc. To access the Dynamic Call Graph Selected Arc Pop-up Menu, click mouse button 2 on an arc in the diagram. The menu is displayed with the following choices: o Display information... o Center. Related Information o Dynamic Call Graph Selected Node Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ 17.10. Dynamic Call Graph Selected Node Pop-up Menu ΓòÉΓòÉΓòÉ The pop-up menus allow you to quickly access features that are frequently used. The Dynamic Call Graph Selected Node Pop-up Menu contains actions that can be applied to a selected node. To access the Dynamic Call Graph Selected Node Pop-up Menu, click mouse button2 on a node in the diagram. The menu is displayed with the following choices: o Display information... o Center o Hide node o Edit function. Related Information o Dynamic Call Graph Selected Arc Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ 17.11. Display Information... Choice ΓòÉΓòÉΓòÉ The Display information... choice displays a window with information about a selected node or arc. To access the Display information... choice, click mouse button 2 on a node or an arc in the Dynamic Call Graph diagram. For nodes, the information window displayed depends on what type of component the selected node represents. You set the type of component the nodes represent by selecting View > Nodes of, and then selecting Functions, Classes (only selectable if you are analyzing a C++ program), or Executables. The Display information... choice displays the: o Function Information Window when the nodes represent functions. o Class Information Window when the nodes represent classes. o Executable Information Window when the nodes represent executables. For arcs, the Who Calls Whom window is displayed. Related Information o Keys Help. ΓòÉΓòÉΓòÉ 17.11.1. Dynamic Call Graph Function Information Window ΓòÉΓòÉΓòÉ Use the Function Information window to display information about a selected function. When the Nodes of choice is set to Functions, you can display the Function Information window by either double-clicking on a node or clicking mouse button2 on a node, and then selecting Display information... from the pop-up menu. The following information is provided in the Function Information window: o Function name o Object file name o Executable name o Execution time o Number of calls o Time on stack The following push buttons are also in the window: Who calls me Select this push button to display only the selected node, and the node or nodes that called the selected node. To return to the diagram, select Restore graph from the View menu. Whom do I call Select this push button to display only the selected node and the nodes that the selected node calls. To return to the diagram, select Restore graph from the View menu. Cancel Closes the window. Help Displays Help. Note: If the trace file does not have time stamps: o The Execution Time and Time on stack will not be displayed. o All nodes will be displayed in the same color and size, and the Scale node sizes choice will be disabled. Related Information o Who Calls Whom Window o Dynamic Call Graph o Analyze Trace Window. o Keys Help. ΓòÉΓòÉΓòÉ 17.11.2. Dynamic Call Graph Class Information Window ΓòÉΓòÉΓòÉ Use the Class Information window to display information about a selected class. When the Nodes of choice is set to Classes, you can display the Class Information window by either double-clicking on a node or clicking mouse button2 on a node, and then selecting Display information... from the pop-up menu. The following information is provided in the Class Information window: o Class name o Names of member functions and their associated statistics o Execution time o Number of calls The following push buttons are also in the window: Who calls me Select this push button to display only the selected node, and the node or nodes that called the selected node. To return to the diagram, select Restore graph from the View menu. Whom do I call Select this push button to display only the selected node and the nodes that the selected node calls. To return to the diagram, select Restore graph from the View menu. Cancel Closes the window. Help Displays Help. Note: If the trace file does not have time stamps: o Execution time will not be displayed. o All nodes will be displayed in the same color and size, and the Scale node sizes choice will be disabled. Related Information o Who Calls Whom Window o Dynamic Call Graph o Analyze Trace Window o Keys Help. ΓòÉΓòÉΓòÉ 17.11.3. Dynamic Call Graph Executable Information Window ΓòÉΓòÉΓòÉ Use the Executable Information window to display information about a selected executable. When the Nodes of choice is set to Executables, you can display the Executable Information window by either double-clicking on a node or clicking mouse button2 on a node, and then selecting Display information... from the pop-up menu. The following information is provided in the Executable Information window: o Executable name o Member functions for the executable and associated data o Execution time o Number of calls The following push buttons are also in the window: Who calls me Select this push button to display only the selected node, and the node or nodes that called the selected node. To return to the diagram, select Restore graph from the View menu. Whom do I call Select this push button to display only the selected node and the nodes that the selected node calls. To return to the diagram, select Restore graph from the View menu. Cancel Closes the window. Help Displays Help. Note: If the trace file does not have time stamps: o Execution time will not be displayed. o All nodes will be displayed in the same color and size, and the Scale node sizes choice will be disabled. Related Information o Who Calls Whom Window o Dynamic Call Graph o Analyze Trace Window o Keys Help. ΓòÉΓòÉΓòÉ 17.11.4. 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, either double-click on an arc or click mouse button2 on an arc, and then select Display information... from the pop-up menu. The Who Calls Whom window shows the name of the calling component (function, class, or executable), the called component, and the number of times the call was made. The window also contains the following push buttons: Find caller Selects and centers the node that makes the call represented by the selected arc. Find callee Selects and centers the node that is called by the call represented in the selected arc. Cancel Closes the window. Help Displays Help text. Related Information o Dynamic Call Graph Function Information Window o Dynamic Call Graph o Analyze Trace Window. o Keys Help. ΓòÉΓòÉΓòÉ <hidden> Center Choice ΓòÉΓòÉΓòÉ Select the Center choice to center the selected arc or node in the diagram window. Related Information o Keys Help. ΓòÉΓòÉΓòÉ <hidden> Hide Node Choice ΓòÉΓòÉΓòÉ Select the Hide node choice to remove the selected node and all arcs connected to it from the diagram. This choice makes it easier to select nodes on a busy graph. If only one node is displayed in the diagram, it cannot be removed. To show hidden nodes and arcs again, select View > Restore graph. Note: If the Who Calls Whom or Who Calls Me push button is selected, hidden nodes and arcs related to the selected node will be displayed. Related Information o Keys Help. ΓòÉΓòÉΓòÉ 18. 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 following list describes the diagram components: o Each vertical column represents a function. o The thickness of each line represents a unit of time called a time slice. o 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% 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 percentage that are used. The trace is displayed at 100% 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: o Menu Bar Summary The choices available from the Execution Density diagram menu bar are: - Trace file - Edit - View - Options - Project - Help. o Status Area The Status Area provides information about the following: - Trace description - Time slice - Selected region - Filters - Selected object. o Current Column Indicator o Vertical Ruler o Execution Density Pop-up Menus - Execution Density Diagram Pop-up Menu. - Execution Density Selected Item Pop-up Menu. Related Information o Call Nesting Diagram o Dynamic Call Graph o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o Keys Help. ΓòÉΓòÉΓòÉ 18.1. Execution Density Trace File Menu ΓòÉΓòÉΓòÉ The following choices are available from the Execution Density 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 the Performance Analyzer Exits the Performance Analyzer. Related Information o Analyze Trace Window o Call Nesting Diagram o Dynamic Call Graph o Statistics Diagram o Time Line Diagram o 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 o Using the Analyze Trace Window o 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 o Open As Choice o 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 o Open As Choice o 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 o Open As Choice o 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 o Open As Choice o 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 o Open As Choice o 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. o OK o Font... o Job properties... o Cancel o Help Related Information o 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 o Keys Help. ΓòÉΓòÉΓòÉ 18.1.4. Window Manager Choice ΓòÉΓòÉΓòÉ Select the Window Manager choice to display the Window Manager window. Related Information o Performance Analyzer - Window Manager o Keys Help. ΓòÉΓòÉΓòÉ 18.1.5. Exit the Performance Analyzer ΓòÉΓòÉΓòÉ Select Exit the Performance Analyzer to close the Performance Analyzer and all the active windows. Related Information o 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 range in the diagram. Select all Select the entire Execution Density diagram. Related Information o Call Nesting Diagram o Dynamic Call Graph o Statistics Diagram o Time Line Diagram o 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 o Execution Density Diagram Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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. To search for a function call or return: 1. Enter the function name in the Find entry field. If you don't know the function name, you can use wildcard characters (* and ?) in the entry field, as follows: o Use an asterisk (*) to represent 0 or more arbitrary characters. For example, enter: - * to display a list of all function names. - b* to display all function names, regardless of length, that begin with the letter b. - *b to display all function names that end with the letter b. o Use a question mark (?) to represent a single arbitrary character. For example, enter ?b* to display all function names that start with any character and have the letter b as their second character. Note: Wildcards are especially useful when you are searching for a fully qualified C++ function name (for example, myClass:: function[parameter] ). 2. Click on the Case sensitive check box if you want to enable case sensitive searching. 3. Click on the OK push button. 4. Click on the name of a function in the list box. 5. Select the thread that you want searched. 6. Click on the appropriate radio button to search for occurrences of when the function was: o Called o Returned o Either called or returned. 7. Select the appropriate push button to continue: o OK o Cancel o Help. Note: The function is highlighted when found. Related Information o Find Next Choice o Keys Help. ΓòÉΓòÉΓòÉ 18.2.2. Find Next Choice ΓòÉΓòÉΓòÉ Select the Find next choice to locate the next occurrence 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 o Execution Density Diagram Pop-up Menu o 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 o Select Time Range Window o Analyze Trace Window o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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: o seconds (s) o milliseconds (ms) o microseconds (us) 2. Use the spin buttons to select the time you want to display. 3. Select the appropriate push button to continue: o OK o Cancel o Help. Related Information o Select Time Range Window o Call Nesting Diagram o Execution Density Diagram o Time Line Diagram o Keys Help. ΓòÉΓòÉΓòÉ 18.2.4. Select Time Range... Choice ΓòÉΓòÉΓòÉ Select the Select time range... choice to chose to view a specific time period. When you select the Select time range... choice, the Select Time Range window appears. Related Information o Select Time Window o Analyze Trace Window o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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: o seconds (s), o milliseconds (ms), o 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: o seconds (s), o milliseconds (ms), o microseconds (us). 5. Select the appropriate push button to continue: o OK o Cancel o Help. Related Information o Call Nesting Diagram o Execution Density Diagram o Time Line Diagram o Analyze Trace Window o Select Time Window o 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 o Select Time Window o Select Time Range Window o 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 o Call Nesting Diagram o Dynamic Call Graph o Statistics Diagram o Time Line Diagram o 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, pressing the + key on the numeric key pad or Shift and the + key on the keyboard will perform the same function. Related Information o Zoom Out Choice o Zoom to Selected Range Choice o Execution Density Selected Item Pop-up Menu o 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, pressing the minus key (-) on the numeric key pad or Shift and the - key on the keyboard will perform the same function. Related Information o Zoom In Choice o Zoom to Selected Range Choice o Execution Density Selected Item Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ 18.3.3. Zoom to Selected Range Choice ΓòÉΓòÉΓòÉ Select the Zoom to selected range choice 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 2 to click on the highlighted area. From the displayed Selected Item Pop-up Menu, choose Zoom to selected range. Related Information o Zoom In Choice o Zoom Out Choice o Execution Density Selected Item Pop-up Menu o 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 o Analyze Trace Window o Execution Density Diagram Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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: o Move the slider arm to the Maximum position to increase the number of pages in the diagram. o 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: o OK o Cancel o Help. Related Information o Analyze Trace Window o Execution Density Diagram o Time Line Diagram. o 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 o Analyze Trace Window o Execution Density Diagram Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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: o OK o Cancel o Help Viewing All Functions 1. To select all functions, select the Select all push button. 2. Select the appropriate push button to continue: o OK o Cancel o Help Related Information o Call Nesting Diagram o Execution Density Diagram o Dynamic Call Graph o Analyze Trace Window. o 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 o Analyze Trace Window o Execution Density Diagram Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ 18.3.6.1. Include Threads Window ΓòÉΓòÉΓòÉ Use the Include Threads window to select or isolate specific threads. Use the mouse to highlight your thread selection. You can choose a particular thread or all threads. Select Options > Color... to see the range of execution times represented by the colors of the lines in the diagram. Note: The percentages of execution time are based upon the total execution time of the selected threads, not the total execution time. When you change 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: o OK o Select all o Deselect all o Cancel o Help. Selecting All Threads To select all threads: 1. Highlight All threads to select all threads. 2. Select the appropriate push button to continue: o OK o Select all o Deselect all o Cancel o Help Related Information o Dynamic Call Graph o Execution Density Diagram o Analyze Trace Window o 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 o Call Nesting Diagram o Dynamic Call Graph o Statistics Diagram o Time Line Diagram o 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 o Execution Density Diagram Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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 of 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 percentage of time 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: o OK o Cancel o Help 4. To restore the initial defaults, select the Settings choice from the Options menu, then select Restore initial defaults. Related Information o Execution Density Diagram. o Hints for Using the Performance Analyzer o 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 o Execution Density Diagram Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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: o OK o Cancel o Help. Related Information o Execution Density Diagram. o Keys Help. ΓòÉΓòÉΓòÉ 18.4.3. Correlation... Choice ΓòÉΓòÉΓòÉ Select the Correlation... choice to mark a point in time 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 Correlation... choice, the Correlation window appears. Related Information o Execution Density Selected Item Pop-up Menu o Analyze Trace Window o 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 o Execution Density Status Area o Keys Help. ΓòÉΓòÉΓòÉ <hidden> Execution Density 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 Execution Density Status Area window include: o Trace Description o Time Slice o Selected Region o Filters o Selected Object Select the appropriate check box to continue. Related Information o Call Nesting Status Area Window o Dynamic Call Graph Status Area Window o Status Area Window. o 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 help Choose to either enable or disable displaying the help text when the mouse pointer hovers over the tool bar buttons. Related Information o 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 Saves the current session settings. Restore initial defaults Restores the original settings. Related Information o Save Choice o Restore Initial Defaults Choice o Keys Help. ΓòÉΓòÉΓòÉ 18.4.6.1. Save Choice ΓòÉΓòÉΓòÉ Select the Save choice to save the current settings. These settings are stored in the IPERF.INI file and remain active until that file is erased. To restore the default settings, select the Restore initial defaults choice. Related Information o Restore Initial Defaults Choice o 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 o Save Choice. o 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 o Search Paths Window o Trace Generation Window o 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 o Locate Executable Window o Locate Source File Window o Search Paths Window o Starting the Performance Analyzer from WorkFrame o 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. VisualAge for C++ Help Menu Items Launch the VisualAge for C++ documentation associated with the menu choice. These choices are available when you start the Performance Analyzer from WorkFrame. Product information Displays information about the Performance Analyzer. Related Information o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 select each column. Use the mouse to select 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 o Execution Density Status Area o Keys Help. ΓòÉΓòÉΓòÉ 18.8. Execution Density Vertical Ruler ΓòÉΓòÉΓòÉ The Vertical Ruler, located to the left of the diagram, shows the approximate time of events on the screen. To change the time scale, select the Scale pages... choice from the View menu, and the Scale Pages window appears. Related Information o Execution Density Status Area o 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 what appears in 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 total time, start time, and end time for 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 o Call Nesting Status Area o Dynamic Call Graph Status Area o Time Line Status Area o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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 o Execution Density Status Area Window o Execution Density Diagram. o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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 o Execution Density Status Area Window o Execution Density Diagram. o Keys Help. ΓòÉΓòÉΓòÉ <hidden> Selected Region Status Line ΓòÉΓòÉΓòÉ Selected region displays the total time, start time, and end time for 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 1 and drag the pointer across the region of the diagram that you want to check. Release mouse button 1 to end the highlighting. Elapsed time Shows how long the selected region took to execute. Start time Shows the point where you started selecting End time Displays the point where you stopped. So, if you started selecting on the main function at 2.3 seconds and ended at 17.5 seconds, the Elapsed time would be 15.2 seconds, the Start time would be 2.3 seconds, and the End time would be 17.5 seconds. Related Information o Execution Density Status Area Window o Execution Density Diagram. o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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 o Include Functions Window o Include Threads Window o Execution Density Diagram o Execution Density Status Area Window. o Keys Help. ΓòÉΓòÉΓòÉ <hidden> Selected Object Status Line ΓòÉΓòÉΓòÉ Selected object displays the name of the selected object. Use mouse button 1 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 o Execution Density Diagram o Execution Density Status Area Window. o 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. This pop-up menu contains most of the choices from the Edit and Options menus. To access this menu, use mouse button 2 to click on the background area of the diagram. The menu is displayed with the following choices: o Find function... o Find next o Zoom in o Zoom out o Scale pages... o Include functions... o Include threads... o Color... o Column width... Related Information o Execution Density Selected Item Pop-up Menu o Execution Density Diagram o Keys Help. ΓòÉΓòÉΓòÉ 18.11. 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 2. This menu contains the following choices: o Zoom to selected range o Correlation... o Edit function Related Information o Execution Density Diagram Pop-up Menu o Execution Density Diagram o Keys Help. ΓòÉΓòÉΓòÉ 19. Statistics Diagram ΓòÉΓòÉΓòÉ The Statistics diagram gives you a textual report of execution time by function, class (only if you are analyzing a C++ program), or executable. Use this information to find hot spots in the overall program execution. The Statistics diagram has two panes: Summary and Details. The Summary pane lists general facts about your program's overall execution. The Details pane lists specific facts about the execution of individual program components. You can select the type of information you want displayed in this pane. If you want to display information about: o Functions, select View > Details on > Functions. o Classes, select View > Details on > Classes. Note: You can only select this choice if you are analyzing a C++ program. o Executables, select View > Details on > Executables. You can resize the panes vertically. To resize a pane, position the mouse pointer on the split bar, and then press and hold mouse button 1 as you drag the bar. Release the mouse button when the pane is the size you want. Note: Times are shown in milliseconds. Areas of the Statistics Diagram Window o Menu Bar The following choices are available from the Statistics diagram menu bar: - Trace file - View - Options - Project - Help. o Summary Pane o Details Pane. Related Information o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o Keys Help. ΓòÉΓòÉΓòÉ 19.1. Statistics Summary Pane ΓòÉΓòÉΓòÉ The Summary pane is in the top area of the window. You must scroll the pane to view all of the information. To resize the pane vertically, position the mouse pointer on the split bar, and then press and hold mouse button 1 as you drag the bar. Release the mouse button when the pane is the size you want. Information provided in the Summary pane is as follows: o Executable name o Trace file description Note: A trace file description will only appear if a description was entered when the file was created. o Execution date o Execution time o Number of executables generating events o Number of classes generating events (only if you are analyzing a C++ program) o Number of functions generating events o Number of threads generating events o Total number of events o Total number of annotations o Number of user events o Maximum call nest depth o Number of trace buffer flushes o Total trace time excluding overhead o Trace overhead. Related Information o Statistics Details Pane o Hints for Using the Performance Analyzer o Keys Help. ΓòÉΓòÉΓòÉ 19.2. Statistics Details Pane ΓòÉΓòÉΓòÉ The Details pane is in the bottom area of the window. You must scroll the pane to view all of the information. To resize the pane vertically, position the mouse pointer on the split bar, and then press and hold mouse button 1 as you drag the bar. Release the mouse button when the pane is the size you want. The Details pane has a left and right pane. The left pane displays the fully qualified name of the component on which the statistics have been gathered. Other information provided on the left side of the Details pane varies depending on the View > Details on setting. If Details on is set to: o Functions, you see columns with the following headings: Function, Object file, and Executable. o Classes, you see one column with the heading Class. o Executables, you see one column with the heading 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: o % of execution o % on stack o Number of calls o Execution time o Time on stack o Minimum call o Maximum call o 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 o Statistics Summary Pane o Hints for Using the Performance Analyzer o 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 statistical 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 the Performance Analyzer Exits the Performance Analyzer and closes all windows. Related Information o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Time Line Diagram o Keys Help. ΓòÉΓòÉΓòÉ 19.3.1. Open As Cascading Choice ΓòÉΓòÉΓòÉ Select the Open as cascading choice to open another Statistics diagram window or to open one of the other diagrams. 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 o Using the Analyze Trace Window o Keys Help. ΓòÉΓòÉΓòÉ 19.3.1.1. Call Nesting Choice ΓòÉΓòÉΓòÉ Select the Call Nesting choice to display the current trace file in the Call Nesting diagram. Access this choice by selecting Trace file>Open as. Related Information o Open As Choice o Keys Help. ΓòÉΓòÉΓòÉ 19.3.1.2. Dynamic Call Graph Choice ΓòÉΓòÉΓòÉ Select the Dynamic Call Graph choice to display the current trace file in the Dynamic Call Graph diagram. Access this choice by selecting Trace file>Open as. Related Information o Open As Choice o Keys Help. ΓòÉΓòÉΓòÉ 19.3.1.3. Execution Density Choice ΓòÉΓòÉΓòÉ Select the Execution Density choice to display the current trace file in the Execution Density diagram. Access this choice by selecting Trace file>Open as. Related Information o Open As Choice o Keys Help. ΓòÉΓòÉΓòÉ 19.3.1.4. Statistics Choice ΓòÉΓòÉΓòÉ Select the Statistics choice to display the current trace file in the Statistics diagram. Access this choice by selecting Trace file>Open as. Related Information o Open As Choice o Keys Help. ΓòÉΓòÉΓòÉ 19.3.1.5. Time Line Choice ΓòÉΓòÉΓòÉ Select the Time Line choice to display the current trace file in the Time Line diagram. Access this choice by selecting Trace file>Open as. Related Information o Open As Choice o Keys Help. ΓòÉΓòÉΓòÉ 19.3.2. Save As Text... Choice ΓòÉΓòÉΓòÉ Select the Save as text... choice to save the Statistics diagram data as an ASCII file. When you select the Save as text... choice, the Save As Text window appears. Related Information o Keys Help. ΓòÉΓòÉΓòÉ 19.3.2.1. Save As Text Window ΓòÉΓòÉΓòÉ The Save As Text window lets you select the path and file name in which the Performance Analyzer will save the data contained in the Summary and Details panes of the Statistics diagram. The data is saved as an ASCII file. Note: Save As Text does not save the binary trace file. Related Information o 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. o OK o Font... o Job properties... o Cancel o Help Related Information o 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 o Keys Help. ΓòÉΓòÉΓòÉ 19.3.5. Window Manager Choice ΓòÉΓòÉΓòÉ Select the Window Manager choice to display the Window Manager window. Related Information o Performance Analyzer - Window Manager o Keys Help. ΓòÉΓòÉΓòÉ 19.3.6. Exit the Performance Analyzer Choice ΓòÉΓòÉΓòÉ Select Exit the Performance Analyzer to close all Performance Analyzer windows and end the application. Related Information o Keys Help. ΓòÉΓòÉΓòÉ 19.4. Statistics View Menu ΓòÉΓòÉΓòÉ The choices from the View menu are: Details on > Select to view the Details pane by function information, class information (only if you are analyzing a C++ program), or executable information. Include threads... Select which threads to include in the diagram. Sort > Select how you want to sort the Details pane. Related Information o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Time Line Diagram o Keys Help. ΓòÉΓòÉΓòÉ 19.4.1. Details On Cascading Choice ΓòÉΓòÉΓòÉ Select the Details on choice to display the following choices: Functions Displays statistics in the Details pane for each traced function in your program. Classes Displays statistics in the Details pane for each traced class in your program. Notes: 1. Class execution time is calculated by totalling the execution times for all member functions contained in the class. Class time on stack is calculated by totalling the time on stack for all member functions contained in the class. 2. When a class occurs in more than one executable or DLL, the statistics shown represent the sum of the statistics for each occurrence of the class. 3. Statistics for functions that are not part of any class are included in the C_Function class listed on the Details pane. Executables Displays statistics in the Details pane for each traced executable in your program. Note: The execution time for an executable is calculated by totalling the execution times for all functions contained in the executable. Time on stack is calculated by totalling the time on stack for all functions contained in the executable. Related Information o Find... Choice o Keys Help. ΓòÉΓòÉΓòÉ 19.4.1.1. Functions Choice ΓòÉΓòÉΓòÉ Select the Functions choice to view the functions included in the trace. You can access this choice by selecting View > Details on > Functions on the Statistics diagram. A check mark is displayed next to the choice when it is selected. Related Information o Classes Choice o Executables Choice o Keys Help. ΓòÉΓòÉΓòÉ 19.4.1.2. Classes Choice ΓòÉΓòÉΓòÉ Select the Classes choice to view the classes included in the trace. You can access this choice by selecting View > Details on > Classes on the Statistics diagram. A check mark is displayed next to the choice when it is selected. Notes: 1. Class execution time is calculated by totalling the execution times for all member functions contained in the class. Class time on stack is calculated by totalling the time on stack for all member functions contained in the class. 2. When a class occurs in more than one executable or DLL, the statistics shown represent the sum of the statistics for each occurrence of the class. 3. Statistics for functions that are not part of any class are included in the C_Function class listed on the Details pane. Related Information o Functions Choice o Executables Choice o Keys Help. ΓòÉΓòÉΓòÉ 19.4.1.3. Executables Choice ΓòÉΓòÉΓòÉ Select the Executables choice to view statistics on executables included in the trace. You can access this choice by selecting View > Details on > Executables on the Statistics diagram. A check mark is displayed next to the choice when it is selected. Note: The execution time for an executable is calculated by totalling the execution times for all functions contained in the executable. Time on stack is calculated by totalling the time on stack for all functions contained in the executable. Related Information o Functions Choice o Classes Choice o 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 threads you affect the percentages. Related Information o Keys Help. ΓòÉΓòÉΓòÉ 19.4.2.1. Include Threads Window ΓòÉΓòÉΓòÉ Use the Include Threads window to specify which threads you want to see data for in the Statistics diagram. Note: The percentages of execution time in the diagram are based upon the total execution time of the selected threads, not the total execution time. When you change threads you affect the percentages. Selecting Specific Threads To select a specific thread: 1. Click on the name of the thread you want to display. Threads are highlighted when selected. 2. Select the appropriate push button to continue: o OK o Select all o Deselect all o Cancel o Help. Selecting All Threads To select all threads: 1. Click on the Select all push button in the Include Threads window to select all threads. 2. Select the appropriate push button to continue: o OK o Select all o Deselect all o Cancel o Help Related Information o Dynamic Call Graph o Execution Density Diagram o Analyze Trace Window o Keys Help. ΓòÉΓòÉΓòÉ 19.4.3. Sort Cascading Choice ΓòÉΓòÉΓòÉ Select the Sort choice to sort the Details window on one of its columns. When you select Sort, a cascaded menu is displayed with the following choices. Invalid choices are grayed out. o Function name o Class name (You can only select this choice if you are analyzing a C++ program.) o Object file name o Executable name o Execution time o Time on call stack o Number of calls o Minimum call o Maximum call o Average call. Related Information o Analyze Trace Window o 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 pane sorts all data by function name. Related Information o Sort Choice o Object file name o Executable name o Execution time o Time on call stack o Number of calls o Minimum call o Maximum call o Average call. o Keys Help. ΓòÉΓòÉΓòÉ 19.4.3.2. Class Name Choice ΓòÉΓòÉΓòÉ Select the Class name choice to sort the class names in the Details pane alphabetically. Related Information o Sort Choice o Object file name o Executable name o Execution time o Time on call stack o Number of calls o Minimum call o Maximum call o Average call. o Keys Help. ΓòÉΓòÉΓòÉ 19.4.3.3. Object File Name Choice ΓòÉΓòÉΓòÉ Select the Object file name choice to sort on the Object file column in the Details pane in alphabetical order. Select the choice and the Details pane sorts all data by object file name. Related Information o Sort Choice o Function name o Executable name o Execution time o Time on call stack o Number of calls o Minimum call o Maximum call o Average call. o Keys Help. ΓòÉΓòÉΓòÉ 19.4.3.4. 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 pane sorts all data by executable name. Related Information o Sort Choice o Function name o Object file name o Execution time o Time on call stack o Number of calls o Minimum call o Maximum call o Average call. o Keys Help. ΓòÉΓòÉΓòÉ 19.4.3.5. 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 pane sorts all data by execution time. Each entry in this column designates the total execution time spent in a particular function. Related Information o Sort Choice o Function name o Object file name o Executable name o Time on call stack o Number of calls o Minimum call o Maximum call o Average call. o Keys Help. ΓòÉΓòÉΓòÉ 19.4.3.6. 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 pane 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 o Sort Choice o Function name o Object file name o Executable name o Execution time o Number of calls o Minimum call o Maximum call o Average call. o Keys Help. ΓòÉΓòÉΓòÉ 19.4.3.7. 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 pane 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 o Sort Choice o Function name o Object file name o Executable name o Execution time o Time on call stack o Minimum call o Maximum call o Average call. o Keys Help. ΓòÉΓòÉΓòÉ 19.4.3.8. 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 pane 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 o Sort Choice o Function name o Object file name o Executable name o Execution time o Time on call stack o Number of calls o Maximum call o Average call. o Keys Help. ΓòÉΓòÉΓòÉ 19.4.3.9. Maximum Call Choice ΓòÉΓòÉΓòÉ Select the Maximum call choice to sort the Maximum call column in the Details window in descending order. The function with the most calls is placed at top. Select the choice and the Details pane 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 o Sort Choice o Function name o Object file name o Executable name o Execution time o Time on call stack o Number of calls o Minimum call o Average call. o Keys Help. ΓòÉΓòÉΓòÉ 19.4.3.10. 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 pane 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 o Sort Choice o Function name o Object file name o Executable name o Execution time o Time on call stack o Number of calls o Minimum call o Maximum call o 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 functions, classes (only if you are analyzing a C++ program), or executables in the diagram. 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o Keys Help. ΓòÉΓòÉΓòÉ 19.5.1. Find... Choice ΓòÉΓòÉΓòÉ Select the Find... choice to search for functions, classes (only if you are analyzing a C++ program), or executables in the Statistics diagram. Note: Before you select the Find... choice, choose the type of component you want to search for by selecting View > Details on, and then selecting Functions, Classes, or Executables. When you select the Find... choice, a Find window appears. The Find window that is displayed depends on what type of component (function, class, or executable) you are searching for. If you are searching for: o A function, the Find Function window appears. o A class, the Find Class window appears. o An executable, the Find Executable window appears. Related Information o 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: Font entry field Type a font name in this entry field or click on the scroll bar to see a list of choices and select a name from the list. Font Style entry field Type a font style in this entry field or click on the scroll bar to see a list of choices and select a style from the list. Size entry field Type a font size in this entry field or click on the scroll bar to see a list of choices and select a size from the list. 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. Cancel push button Closes the window without making changes. Related Information o 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 help Choose to either enable or disable displaying the help text when the mouse pointer hovers over the tool bar buttons. Related Information o 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 Saves the current session settings. Restore initial defaults Restores the original settings. Related Information o Save Choice o Restore Initial Defaults Choice o Keys Help. ΓòÉΓòÉΓòÉ 19.5.4.1. Save Choice ΓòÉΓòÉΓòÉ Select the Save choice to save the current settings. These settings are stored in the IPERF.INI file and remain active until that file is erased. To restore the default settings, select the Restore defaults choice. Related Information o Restore Initial Defaults Choice o 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 o Save Choice o 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 o Search Paths Window o 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 o Locate Executable Window o Locate Source File Window o Search Paths Window o Starting the Performance Analyzer from WorkFrame o 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. VisualAge for C++ Help Menu Items Launch the VisualAge for C++ documentation associated with the menu choice. These choices are available when you start the Performance Analyzer from WorkFrame. Product information Displays information about the Performance Analyzer. Related Information o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o Keys Help. ΓòÉΓòÉΓòÉ 20. 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 is 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 20 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 pink circle 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: o Menu Bar Summary The following choices are available from the Time Line diagram menu bar: - Trace file - Edit - View - Options - Project - Help. o Status area... The Status Area provides information about the following: - Trace description - Time slice - Selected region o Vertical Ruler o Time Line Pop-up Menus - Time Line Diagram Pop-up Menu. - Time Line Selected Item Pop-up Menu. Related Information o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Hints for Using the Performance Analyzer o 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 the Performance Analyzer Exits the Performance Analyzer. Related Information o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o 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 o Using the Analyze Trace Window o 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 o Open As Choice o 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 o Open As Choice o 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 o Open As Choice o 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 o Open As Choice o 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 o Open As Choice o 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. o OK o Font... o Job properties... o Cancel o Help Related Information o 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 o Keys Help. ΓòÉΓòÉΓòÉ 20.1.4. Window Manager Choice ΓòÉΓòÉΓòÉ Select the Window Manager choice to display the Window Manager window. Related Information o Performance Analyzer - Window Manager o Keys Help. ΓòÉΓòÉΓòÉ 20.1.5. Exit the Performance Analyzer Choice ΓòÉΓòÉΓòÉ Select Exit the Performance Analyzer to exit the Performance Analyzer and close all associated windows. Related Information o 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 > Search for a function call or return or a user event. 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 range in the diagram. Select all Select the entire Time Line diagram. Related Information o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Keys Help. ΓòÉΓòÉΓòÉ 20.2.1. Find Cascading Choice ΓòÉΓòÉΓòÉ Select the Find > cascading choice to locate text. Items you can select from the cascaded menu include: Function... Locates the text of function calls and returns. User event... Locates user events Related Information o Find Next Choice o Time Line Diagram Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ 20.2.1.1. Function Choice ΓòÉΓòÉΓòÉ Select the Function... choice to search for function calls and returns. When you select the Function... choice, the Find Function window appears. Related Information o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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. To search for a function call or return: 1. Enter the function name in the Find entry field. If you don't know the function name, you can use wildcard characters (* and ?) in the entry field, as follows: o Use an asterisk (*) to represent 0 or more arbitrary characters. For example, enter: - * to display a list of all function names. - b* to display all function names, regardless of length, that begin with the letter b. - *b to display all function names that end with the letter b. o Use a question mark (?) to represent a single arbitrary character. For example, enter ?b* to display all function names that start with any character and have the letter b as their second character. Note: Wildcards are especially useful when you are searching for a fully qualified C++ function name (for example, myClass:: function[parameter] ). 2. Click on the Case sensitive check box if you want to enable case sensitive searching. 3. Click on the OK push button. 4. Click on the name of a function in the list box. 5. Select the thread that you want searched. 6. Click on the appropriate radio button to search for occurrences of when the function was: o Called o Returned o Either called or returned. 7. Select the appropriate push button to continue: o OK o Cancel o Help. Note: The function is highlighted when found. Related Information o Find Next Choice o Keys Help. ΓòÉΓòÉΓòÉ 20.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 o 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 o Find Window o Time Line Diagram Pop-up Menu o 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 o Select Time Range Window o 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: o seconds (s) o milliseconds (ms) o microseconds (us) 2. Use the spin buttons to select the time you want to display. 3. Select the appropriate push button to continue: o OK o Cancel o Help. Related Information o Select Time Range Window o Call Nesting Diagram o Execution Density Diagram o Time Line Diagram o 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 o Select Time Window o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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: o seconds (s), o milliseconds (ms), o 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: o seconds (s), o milliseconds (ms), o microseconds (us). 5. Select the appropriate push button to continue: o OK o Cancel o Help. Related Information o Select Time Window o Call Nesting Diagram o Execution Density Diagram o Time Line Diagram o Analyze Trace Window o 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 o Select Time Window o Select Time Range Window o 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 scale of the diagram incrementally. Zoom to selected range Magnify the diagram to focus on the highlighted area. Scale pages... Selects the size of the diagram. Related Information o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o 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, pressing the + key on the numeric key pad or Shift and the +key on the keyboard will perform the same function. Related Information o Zoom Out Choice o Zoom to Selected Range Choice o Time Line Selected Item Pop-up Menu o 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 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 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, pressing the minus key (-) on the numeric key pad or Shift and the - key on the keyboard will perform the same function. Related Information o Zoom In Choice o Zoom to Selected Range Choice o Time Line Diagram Pop-up Menu o 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 2 to click on the highlighted area. From the displayed Time Line Selected Item Pop-up Menu, choose Zoom to selected region. Related Information o Zoom In Choice o Zoom Out Choice o Time Line Selected Item Pop-up Menu o 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 o Time Line Diagram Pop-up Menu o Restore Initial Defaults Choice o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram Pop-up Menu o Time Line Selected Item Pop-up Menu o 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 o Time Line Selected Item Pop-up Menu o Restore Initial Defaults Choice o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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: o OK o Help. Related Information o Call Nesting Diagram o Time Line Diagram. o Keys Help. ΓòÉΓòÉΓòÉ 20.4.2. Correlation... Choice ΓòÉΓòÉΓòÉ Select the Correlation... choice to mark a point in time 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 Correlation... choice, the Correlation window appears. Related Information o Time Line Selected Item Pop-up Menu o 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: Font entry field Type a font name in this entry field or click on the scroll bar to see a list of choices and select a name from the list. Font Style entry field Type a font style in this entry field or click on the scroll bar to see a list of choices and select a style from the list. Size entry field Type a font size in this entry field or click on the scroll bar to see a list of choices and select a size from the list. 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. Cancel push button Closes the window without making changes. Related Information o Time Line Diagram Pop-up Menu o 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 o Time Line Diagram Pop-up Menu o Keys Help. ΓòÉΓòÉΓòÉ <hidden> 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. 2. Select the check box to draw separator lines between the threads. A check mark 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: o OK o Apply o Cancel o Help. Related Information o Call Nesting Diagram o Time Line Diagram o 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 window appears. Related Information o 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. Select the following topics to see the choices available in the Status Area window for each applicable diagram: o Call Nesting Status Area Window o Dynamic Call Graph Status Area Window o Execution Density Status Area Window o Time Line Status Area Window. ΓòÉΓòÉΓòÉ <hidden> Time Line 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 Time Line Status Area window include: o Trace Description o Time Slice o Selected Region Related Information o Call Nesting Status Area Window o Execution Density Status Area Window o Dynamic Call Graph Status Area Window o 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 help Choose to either enable or disable displaying the help text when the mouse pointer hovers over the tool bar buttons. Related Information o 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 Saves the current session settings. Restore Initial Defaults Restores the original settings. Related Information o Save Choice o Restore Initial Defaults Choice o Keys Help. ΓòÉΓòÉΓòÉ 20.4.7.1. Save Choice ΓòÉΓòÉΓòÉ Select the Save choice to save the current settings. These settings are stored in the IPERF.INI file and remain active until that file is erased. To restore the default settings, select the Restore initial defaults choice. Related Information o Restore Initial Defaults Choice o 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 o Save Choice o 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 o Search Paths Window o Trace Generation Window o 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 o Locate Executable Window o Locate Source File Window o Search Paths Window o Starting the Performance Analyzer from WorkFrame o 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. VisualAge for C++ Help Menu Items Launch the VisualAge for C++ documentation associated with the menu choice. These choices are available when you start the Performance Analyzer from WorkFrame. Product information Displays information about the Performance Analyzer. Related Information o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Hints for Using the Performance Analyzer o 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 what appears in 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 total time, start time, and end time for a selected region. Related Information o Call Nesting Status Area o Execution Density Status Area o Dynamic Call Graph Status Area o Execution Density Status Area o Keys Help. ΓòÉΓòÉΓòÉ 20.8. Time Line Vertical Ruler ΓòÉΓòÉΓòÉ The Vertical Ruler, located to the left of the diagram, shows the approximate time of events on the screen. To change the time scale, select the Scale pages... choice from the View menu, and the Scale Pages window appears. Related Information o 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 2 to click on the background area of the diagram. The menu is displayed with the following choices: o Find > o Find next o Zoom in o Zoom out o Scale pages... o Font... o Thread layout... Related Information o Time Line Selected Item Pop-up Menu o 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 2. This menu contains the following choices: o Zoom to selected range o Call stack... o Correlation... o Edit function Related Information o Time Line Diagram Pop-up Menu o 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: o EXCEPTION_ACCESS_VIOLATION o EXCEPTION_ILLEGAL_INSTRUCTION o EXCEPTION_INT_DIVIDE_BY_ZERO o EXCEPTION_INT_OVERFLOW o EXCEPTION_PRIV_INSTRUCTION o EXCEPTION_FLT_DENORMAL_OPERAND o EXCEPTION_FLT_DIVIDE_BY_ZERO o EXCEPTION_FLT_INEXACT_RESULT o EXCEPTION_FLT_INVALID_OPERATION o EXCEPTION_FLT_OVERFLOW o EXCEPTION_FLT_STACK_CHECK o EXCEPTION_FLT_UNDERFLOW o EXCEPTION_ARRAY_BOUNDS_EXCEEDED o EXCEPTION_DATATYPE_MISALIGNMENT o EXCEPTION_BREAKPOINT o EXCEPTION_IN_PAGE_ERROR o EXCEPTION_INVALID_DISPOSITION o EXCEPTION_NONCONTINUABLE_EXCEPTION o EXCEPTION_SINGLE_STEP o EXCEPTION_STACK_OVERFLOW These system exceptions appear in the Call Nesting, Time Line, and Statistics diagrams. In the Call Nesting and Time Line diagrams, system exceptions appear as follows: System Exception: Guard page violation In the Call Nesting diagram, select Edit > Find > User event to locate system exception user events. Related Information o Find User Event Window o Call Nesting Diagram o Statistics Diagram o Time Line Diagram o Trace Generation Window o 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: o Hint 1: Reduce the amount of trace data the Performance Analyzer collects. o Hint 2: Use Performance Analyzer features to customize your trace file. o Hint 3: Use a combination of diagrams to understand your program. o Hint 4: Use correlation to see different aspects of a point of interest. o Hint 5: Use the Dynamic Call Graph's color and size characteristics. o Hint 6: Use the Execution Density diagram to see trends. o Hint 7: Use the zoom function to see details. o Hint 8: Find patterns of calls and returns. o Hint 9: Place annotations in your trace files. o 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: o Creating a Customized Trace File o Enabling and Disabling Components o Selecting the Call Depth for Each Thread o Using Time Stamps o Setting and Removing Triggers o Starting and Stopping the Performance Analyzer from Your Program o Trace On Push Button o Trace Off Push Button ΓòÉΓòÉΓòÉ 22.2. Hint 2: Use Performance Analyzer features to customize your trace file. ΓòÉΓòÉΓòÉ o 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 <iperf.h> Note: If you want to insert the prototype yourself, the prototypes for C and C++ programs are as follows: C Prototype void PERF (const char* string); C++ Prototype extern "C" {void PERF(const char* 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. o The CPPWPA3.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. o 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. o You can also trace APIs by linking to the Performance Analyzer's traceable versions of the libraries: _KERNEL.LIB, _USER32.LIB, and _GDI32.LIB. 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 program components (functions, classes [only if you are analyzing a C++ program], or executables). In this diagram, a node represents a component and an arc, which is displayed between a pair of nodes, represents a call from one component to another. Double-click on any node to display a window that provides both the name of the represented component 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 maximum execution time spent in any component. Arc color is based on the maximum number of calls between any two pairs of components. The following table explains how the Dynamic Call Graph uses node color. Note: Class execution time is calculated by totalling the execution times for all member functions contained in the class. +--------------------------------------------------------+ |Node Color: |Indicates: | |---------------+----------------------------------------| |---------------+----------------------------------------| |Gray |Less than 1/8 of the maximum execution | | |time was spent in the component. | |---------------+----------------------------------------| |Blue |Between 1/8 and 1/4 of the maximum | | |execution time was spent in the | | |component. | |---------------+----------------------------------------| |Yellow |Between 1/4 and 1/2 of the maximum | | |execution time was spent in the | | |component. | |---------------+----------------------------------------| |Red |Greater than 1/2 of the maximum | | |execution time was spent in the | | |component. | +--------------------------------------------------------+ The following table explains how the Dynamic Call Graph uses arc color: +--------------------------------------------------------+ |Arc Color: |Indicates: | |---------------+----------------------------------------| |Green |An arc is selected. | |---------------+----------------------------------------| |Gray |Less than 1/8 of the maximum number of | | |calls made were made between components.| |---------------+----------------------------------------| |Blue |1/8 to 1/4 of the maximum number of | | |calls made were made between components.| |---------------+----------------------------------------| |Yellow |1/4 to 1/2 of the maximum number of | | |calls made were made between components.| |---------------+----------------------------------------| |Red |At least 1/2 of the maximum number of | | |calls made were made between components.| +--------------------------------------------------------+ Node Size For functions, node height is determined by the node's execution time relative to the function that has the greatest execution time. Node width is determined by the node's time on stack relative to the function that has the greatest time on stack. Time on stack is the time spent on the call stack. If a function is waiting for a message, the time spent waiting is logged as time on stack. Note: Time on stack includes all time spent in subroutines. For executables and classes, node height and width are based on execution time; therefore, the nodes representing these components will always be square. Time on stack is not relevant for executables and classes. For more information, see Dynamic Call Graph and Dynamic Call Graph Nodes and Arcs. ΓòÉΓòÉΓòÉ 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% 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. ΓòÉΓòÉΓòÉ o 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. o 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 components 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 component 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. ΓòÉΓòÉΓòÉ 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, operating system functions, and C execution time functions. Performance Analyzer - Window Manager Window The following are shortcut keys for the File menu. Choice Shortcut Keys Exit the Performance Analyzer F3 Trace Generation Window The following are shortcut keys for the Program menu. Choice Shortcut Keys Window Manager Ctrl+W Exit the Performance Analyzer F3 Call Nesting Diagram The following are shortcut keys for the Trace file menu. Choice Shortcut Keys Window Manager Ctrl+W Exit the 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 the Performance Analyzer F3 The following are shortcut keys for the View menu. Choice Shortcut Keys Zoom in Shift++ (plus) or + on the numeric key pad Zoom out Shift+- (minus) or - on the numeric key pad 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 the 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 Shift++ (plus) or + on the numeric key pad Zoom out Shift+- (minus) or - on the numeric key pad Statistics Diagram The following are shortcut keys for the Trace file menu. Choice Shortcut Keys Window Manager Ctrl+W Exit the 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 the 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 Shift++ (plus) or + on the numeric key pad Zoom out Shift+- (minus) or - on the numeric key pad ΓòÉΓòÉΓòÉ <hidden> 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. ΓòÉΓòÉΓòÉ <hidden> 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. ΓòÉΓòÉΓòÉ <hidden> Apply Push Button ΓòÉΓòÉΓòÉ Select the Apply push button to use the selected settings in the current window without making them permanent. ΓòÉΓòÉΓòÉ <hidden> Cancel Push Button ΓòÉΓòÉΓòÉ Select the Cancel push button to exit the current window without saving any changes. ΓòÉΓòÉΓòÉ <hidden> 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. ΓòÉΓòÉΓòÉ <hidden> 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. ΓòÉΓòÉΓòÉ <hidden> 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. ΓòÉΓòÉΓòÉ <hidden> 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. ΓòÉΓòÉΓòÉ <hidden> 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. ΓòÉΓòÉΓòÉ <hidden> Font Push Button ΓòÉΓòÉΓòÉ Select the Font push button in the Printer Settings window to select from available fonts. ΓòÉΓòÉΓòÉ <hidden> 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. ΓòÉΓòÉΓòÉ <hidden> Help Push Button ΓòÉΓòÉΓòÉ Select the Help push button to learn how to use the window that is currently displayed. ΓòÉΓòÉΓòÉ <hidden> OK Push Button ΓòÉΓòÉΓòÉ Select the OK push button to save the changes and close the window. ΓòÉΓòÉΓòÉ <hidden> Remove Push Button ΓòÉΓòÉΓòÉ Select the Remove push button to remove a comment from the Annotate dialog window in the Call Nesting diagram. ΓòÉΓòÉΓòÉ <hidden> Reset Push Button ΓòÉΓòÉΓòÉ Select the Reset push button to return to the default font settings. ΓòÉΓòÉΓòÉ <hidden> Select All Push Button ΓòÉΓòÉΓòÉ Select the Select all push button to select all elements in the window. ΓòÉΓòÉΓòÉ <hidden> 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 o Trace Off Push Button. o Trace On Push Button. o Analyze Trace Window o Using the Analyze Trace Window ΓòÉΓòÉΓòÉ <hidden> 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. ΓòÉΓòÉΓòÉ <hidden> 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 o Trace On Push Button. o Using the Analyze Trace Window ΓòÉΓòÉΓòÉ <hidden> 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 o Trace Off Push Button o Using the Analyze Trace Window ΓòÉΓòÉΓòÉ <hidden> 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 node or nodes that called the selected node. For more information, see the Dynamic Call Graph Function Information window. ΓòÉΓòÉΓòÉ <hidden> 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 node or nodes that the selected node called. For more information, see the Dynamic Call Graph Function Information window. ΓòÉΓòÉΓòÉ 24. Glossary ΓòÉΓòÉΓòÉ Double-click on any term to see its definition: o Annotation o Arc o Buffer Wrapping o Call o Call Depth o Call Nesting Diagram o Class o Component o Correlation o Disable o Disabling Components o Dynamic Call Graph o Enable o Enabling Components o Environment Variable o Event o Executable o Execution Density Diagram o Execution Time o Flush o Function o GDI32.DLL o Hot Spots o KERNEL32.DLL o Maximum Execution Time o Maximum Number of Calls Made o Microseconds (us) o Milliseconds (ms) o Minus Icon o Node o Object Files o Overhead o Pels o Pixels o Plus Icon o Profile Hook o Program/Application Note o Return o Scaling o Seconds (s) o Shortcut Keys o Statistics Diagram o System API calls o Thread o Tic o Time Line Diagram o Time on Stack o Time Slice o Time Stamp o Trace Analysis o Trace Event o Trace File o Trigger o User Event o USER32.DLL o Win32 o Win32 API o Windows NT o Windows 95 ΓòÉΓòÉΓòÉ 25. Limitations of the Performance Analyzer ΓòÉΓòÉΓòÉ Note the following when using the Performance Analyzer: o If you have written customized setjmp or longjmp functions to replace the VisualAge for C++ library versions, the Performance Analyzer will not function correctly. o 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. o 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. o 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. o If you minimize the Trace Generation window, the window of the target application remains in its original state. o If you minimize the Overview window in the Dynamic Call Graph, it does not appear in the list of open applications. o The Performance Analyzer can trace and analyze applications generated by the VisualAge for C++ 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. o The Performance Analyzer cannot generate or analyze trace data for child processes in a multiprocess application. o Tracing applications that are currently being debugged by IDEBUG or analyzed by the Performance Analyzer in another session can cause unpredictable results. o 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. o 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ An annotation is a descriptive comment or an explanatory note that you can add to the Call Nesting diagram. Annotating is like placing a bookmark in the trace file. You can add notes next to the calls and returns about what is being displayed in the diagram. 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ An arc is a directed line connecting two nodes in the Dynamic Call Graph. It shows the relationship between the two nodes. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Average call is the sum of all the time that the function executed divided by the total number of times that the function executed. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ 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 the older events in the buffer. When buffer wrapping is disabled, the data is written to the trace file every time the buffer fills. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ To call is to bring a function into effect, such as specifying the entry conditions and then jumping to an entry point in the function. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Call depth is the number of functions that are on the call stack. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A class is a C++ aggregate that may contain functions, types, and user-defined operators in addition to data. Classes may be defined hierarchically, allowing one class to be an expansion of another, and classes can restrict access to their members. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A component can be an executable, an object, or a function from your program. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Correlation allows you to mark a point in time in a diagram, and then find that same point in another diagram. The Performance Analyzer diagrams that can be correlated are: Call Nesting, Execution Density, and Time Line. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ When a component is disabled, the Performance Analyzer does not record trace analysis data for it in the trace file. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ When you disable a component (an executable, an object file, or a 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ 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 color and size of nodes and the color of arcs show the amount of time spent in each function and the number of calls between functions. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ When a component is enabled, the Performance Analyzer records trace analysis data for it in the trace file. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ When you enable a component (an executable, an object file, or a 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ An environment variable is any of a number of variables that describe the way an operating system is going to run and the devices it is going to recognize. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ An event occurs anytime a function is called or returned. The Performance Analyzer records all events in the trace file. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The Execution Density diagram displays trace data in a vertical dimension scaled by the execution time much like the Time Line diagram does, except that 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 that 0 to 1% of the time slice was used in the function and pink represents that 2 to 5% of the time slice was used. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Execution time is the time during which a program is being executed. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A function is defined by the Performance Analyzer to be a callable section within the program. For the Performance Analyzer, procedures, methods, and subroutines are synonyms of functions. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A dynamic link library that consists of functions for drawing graphical images and displaying text. See also KERNEL32.DLL and USER32.DLL. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Hot spots are areas within a program where a disproportionate amount of time is spent. The Performance Analyzer traces how long a function runs, which helps determine which functions cause hot spots. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A dynamic link library that consists of functions for managing memory, processes, and threads. See also USER32.DLL and GDI32.DLL. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Maximum call is the largest amount of time that the function executed. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The maximum execution time is the amount of time required to execute the component that has the greatest execution time. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The maximum number of calls made is the number of calls made between the two components that contained the greatest number of calls between them. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The Microseconds radio button causes the time to display in microseconds. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The Milliseconds radio button causes the time to display in milliseconds. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Minimum call is the smallest amount of time that the function executed. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The minus icon is displayed beside an executable and an object file in the Trace Generation window when the file cannot be shown or expanded. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A node is the representation of an individual function, class (only if you are analyzing a C++ program), or executable in the Dynamic Call Graph. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Number of calls is the total number of times that the function was called. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Object files are compiler output files that are linked to comprise an executable. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Overhead time is the time it takes to log events in the trace file. The Performance Analyzer measures its overhead and adjusts the timing information accordingly. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Pixels are picture elements. Synonym for pels. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Pels are the smallest area of a display screen capable of being addressed and switched between visible and invisible states. Synonym for pixel and picture element. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ % of execution is the total amount of time that was spent in the function divided by the total time that the application was executing. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ % on stack is the total amount of time that the function was on the stack divided by the total time that the application was executing. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The plus icon is displayed beside executable and object files that can be shown or expanded in the Trace Generation window. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The word program as used in this online help generally refers to the executable file you are tracing. The word application as used in this online help generally refers to the Performance Analyzer. For other uses, program and application can be used synonymously. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A return is a language construct that ends an execution sequence in a procedure. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Scaling is the process of changing the granularity of the detail in a trace diagram by either zooming out to get a bigger picture or zooming in to see the finer points. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The Seconds radio button causes the time to display in seconds. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Shortcut keys are keys used to invoke menu choices. When two key names are joined by a plus sign (+), use these two keys together by holding down the first key, and then pressing 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: o Call Nesting Diagram o Dynamic Call Graph o Execution Density Diagram o Statistics Diagram o Time Line Diagram o Trace Generation Window ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The Statistics diagram provides a textual report of execution time by function. It also provides summary information. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ System API calls are calls made to the operating system through functions located in the following system DLLs: KERNEL32.DLL, USER32.DLL, and GDI32.DLL. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A thread is the smallest unit or path of execution within a process. In Windows, each thread is allocated its own stack from the owning process's 4-GB address space, and each one has its own set of processor registers, called the thread's context. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Approximately 838 nanoseconds. A tic is the smallest unit of time measured by the Performance Analyzer counter. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Time on stack 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 the Dynamic Call Graph. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ 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. If each page represents an overall diagram or 100% view, there is one page. As you magnify the diagram, the number of pages increases, and the time slice value increases. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A trace event is either a call to a function or a return from a function. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A trigger function turns tracing on when it is called and then turns tracing off when it returns. If a trigger function is nested within another trigger function, tracing is turned off only after the outer function returns. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A user event is a call to the Performance Analyzer that is 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. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A dynamic link library that consists of functions for performing user-interface tasks, such as creating windows and sending messages. See also KERNEL32.DLL and GDI32.DLL. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The name of a 32-bit application programming interface (API) developed by Microsoft. See also Win32 API. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ (1) A set of Win32 functions that can be called from source code. (2) A 32-bit version of the 16-bit Windows 3.1 API (native to Windows NT). See also Win32. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ An operating system that the Win32 API is implemented on. It is a portable, high-end operating system, which supports multitasking. It is the only operating system that allows implementation of the Win32 APIs on machine architectures based on processors other than the x86, and it supports multiple processors. See also Win32 API. Windows NT is a trademark of Microsoft Corporation. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ (1) A 32-bit operating system that allows you to run 32-bit applications. Windows 95 is a multitasking, multithreaded operating system that can control multiple programs at once. Each program can have multiple concurrent threads or independently executing subcomponents. (2) A platform that the Win32 API is implemented on. It supports image color matching, modems, and other services. It partially supports asynchronous file I/O, debugging, registry, security, and event-logging functions. Windows 95 is a trademark of Microsoft Corporation.