README.TXT Copyright (C) 1997-2000 Rational Software Corporation. All rights reserved. Rational, the Rational logo, Quantify, Rational Visual Test, and ClearQuest are trademarks or registered trademarks of Rational Software Corporation in the United States and in other countries. Visual C++, Visual Basic, Windows NT, Developer Studio, and Microsoft are trademarks or registered trademarks of the Microsoft Corporation. All other names are used for identification purposes only and are trademarks or registered trademarks of their respective companies. U.S. Registered Patent Nos. 5,193,180 and 5,335,344 and 5,535,329. Licensed under Sun Microsystems Inc.'s U.S. Pat. No. 5,404,499. Other U.S. and foreign patents pending. README for Quantify for Windows, 2001.03.00 ----------------------------------------------------------------- TABLE OF CONTENTS ----------------------------------------------------------------- 1. What's new in Quantify? 2. Requirements 3. Installing Quantify 4. Notes 5. Known problems * Interaction with other applications * Instrumenting programs * Running programs * Working with performance data 6. Contacting Technical Support ----------------------------------------------------------------- 1. What's new in Quantify? ----------------------------------------------------------------- New in Quantify, version 2001.03.00: * Sun's JDK release 1.3 is now supported. However, because it was released so late in the Quantify Beta cycle there are changes from the pre-release versions that must be dealt with manually for now. To use 1.3 you need to do the following: 1. Update the Java.policy file in the %JAVA_ROOT%\jre\security folder to include the following (assumes d:/tools/java/jdk1.3 is %JAVA_ROOT%): grant { permission java.lang.RuntimePermission "loadLibrary.PureJVMPI"; permission java.io.FilePermission "d:/tools/java/jdk1.3/jre/lib/ext/x86/PureJVMPI.dll", "read"; }; 2. Copy PureJVMPI.dll into %JAVA_ROOT%\jre\lib\ext\x86 folder 3. Make sure this directory is included in the path in front of the Quantify product directory. You can also remove PureJVMPI.DLL from the product directory and place it into the x86 folder (see p.2). 4. Make sure that Rational.jar is copied into %JAVA_ROOT%\jre\ext folder and you have this folder in your CLASSPATH environment variable. 5. Start your applet. Use qstart or set _JAVA_OPTIONS=-XrunPureJVMPI:Quantify New in Quantify, version 2000.02.10: * Java support has been added for Java2 compliant JVMs. You can now use Quantify to get function-level information using Sun's JDK release 1.2.2 and 1.3 (tested in pre-release) and other compatible JVMs. Note: A file called Profile.ini has been added to the Quantify product directory to control the pre-filtering of system methods. Refer to this file for details on adding additional filters. * Additional improvements in performance and reliability. New in Quantify 6.5: * Improved performance and reliability. * Improved compatibility with IIS and other services. * Default instrumentation behavior has changed for modules which have no associated debug information. These modules are now instrumented in timed mode by default. This improves both instrumentation and run-time performance. * Quantify is integrated with Rational Robot 7.1, a Rational functional testing tool. You can Quantify applications run with Robot scripts in order to collect performance data. From the "Tools > GUI Playback Options > Diagnostic Tools" tab, select "Rational Quantify". See your Rational Robot documentation for more details. New in Quantify 6.0.2: * Support for Visual C++ 6.0 Service Pack 2. New in Quantify 6.0.1: * The following problems have been corrected: * When Quantify was run from the Visual C++ toolbar, some instrumented applications would fail if Quantify was installed in the default location. * Quantify did not install correctly on French Windows NT. New in Quantify 6.0: * Support for Visual C++ 6.0 and Visual Basic 6.0. Note that applying changes to a running Quantify'd program, using "Edit & Continue" in VC6 is not supported. * Support for profiling VB6 programs run directly within the VB6 shell. The new "Engage Quantify Integration" tool in VB6 allows you to profile programs without first making an executable. This method also helps focus the profile data on your VB code, avoiding the complexity of compiled executables. * You can now select a slow function, procedure, or method reported by Quantify and automatically submit it as a performance defect to ClearQuest, Rational's change request management tool. Simply highlight the function, procedure, or method name and select "Submit ClearQuest Defect" from the shortcut menu. Quantify uses an initialization file, schema_quantify.ini, to map performance data and other information to the relevant fields of the ClearQuest defect submit form. This mapping is based on the ClearQuest sample schema 'Default_App'. If you have edited the sample schema or have created a custom schema, you must modify the schema_quantify.ini file to ensure that data is correctly entered in the submit form. To modify the .ini file, follow the instructions included in schema_quantify.ini, located in the Quantify product directory. * Quantify is integrated with Visual Test 6.0, Rational's functional testing tool. You can profile applications run with Visual Test scripts and send performance data back to the script for immediate logging and analysis. Use the "Run Visual Test scripts with Quantify" tool in the Quantify toolbar in Developer Studio or Visual Test, or add "quantify" to the "Run" command in your test scripts. See your Visual Test documentation for more details. New in Quantify 4.1: * Quantify can now run completely within Microsoft Developer Studio, integrating seamlessly with your development environment. To enable this feature, check the Quantify > Settings > Embed Quantify Views menu item in Developer Studio. Quantify's online help is also now available in Developer Studio's InfoView tab. * VB: At install time, you can now choose to install the Quantify addin for Visual Basic. You will find a new toolbar in VB that lets you directly control Quantify. Note that this addin requires VB5 Service Pack 3 or later; older VB5 installations will display a message at startup to disable the addin dll. Your current VB Service Pack level is displayed in the VB5 splash screen. Service Packs can be freely downloaded at http://msdn.microsoft.com/vstudio/sp/ * Java: The Java virtual machine distributed with Visual Studio 6.0 beta-2 (Msjava.dll version 2613) does not work with Quantify. This is corrected in later versions. The latest release of the virtual machine and SDK is available at http://www.microsoft.com/java/download.htm. * Pie charts have been added to the Function Detail view. Try clicking on them to navigate your data. Also, printing the Function Detail window now prints all panes of the window. * Data-tips have been added to the Call Graph. Try pointing the mouse at a node or an arc in the graph, and letting the pointer hover there. * There is a new way to expand or collapse subtrees in the Call Graph. The "+" and "-" symbols at the right edge of nodes act just as they do in the Windows Explorer: clicking a "+" will show all the immediate subnodes of the node; clicking a "-" will hide the subnodes. A "/" symbol indicates a partially expanded subnode. Select Expand Immediate Descendants from the shortcut menu to fully expand such a node. * Functionality of some API functions has been improved. ----------------------------------------------------------------- 2. Requirements ----------------------------------------------------------------- * PC-compatible Pentium system or above, Intel architecture * Microsoft Windows NT 4.0 with Service Pack 3 or greater * 32 Mb RAM required, 64Mb RAM recommended * Approximately 30 Mb free disk space * 200Mb minimum swap space recommended Notes: * You will need additional disk space to accommodate a growing cache directory as you run Quantify on more programs. * Quantify does not support checked builds of Windows NT. Quantify supports: Architecture: Win32 programs only Compilers: Microsoft Visual C++ (6.0) Note: Quantify, version 2000.02.10 was the last release to support Visual C++ 5.0. There are no known incompatibilities with this release but it is not being actively tested. Microsoft Visual Basic (6.0sp3) Note: Quantify, version 2000.02.10 was the last release to support Visual Basic 5.0. There are no known incompatibilities with this release but it is not being actively tested. Interpreters: Microsoft Visual Basic (6.0sp3) Microsoft virtual machine for Java The version for Msjava.dll should be 2174 or later. The latest release of the virtual machine and SDK is available at: http://www.microsoft.com/java/download.htm Debuggers: Microsoft Visual C++, WinDBG, NTSD Debug formats: COFF, CV4 Debug files: Debug data can be placed in .exe, .pdb, or .dbg files. Quantify can also use .map files, if available. ----------------------------------------------------------------- 3. Installing Quantify ----------------------------------------------------------------- To install Quantify: 1. Verify that your swap space is set to at least 200Mb, the minimum recommended. 2. Run Setup.exe and follow the onscreen instructions. Notes: * You are installing a licensed Rational Software product. The product you have purchased includes either a node-locked or floating license. Please refer to the instructions in the Startup License Key Certificate (included in the product package) for installing a startup license key to get started using the product. For detailed information about Rational Software licensing and how to work with node-locked and floating licenses, please refer to the Rational License Key Administrator online Help (Licadmin.hlp), available by clicking the Help button in the Rational License Key Administrator. * The Rational Solutions for Windows install disk includes numerous Rational Software products. However, the startup license key you received can be used to run only the product you purchased. If you would like to install and evaluate other Rational Software products that are available on the install disk but that you have not purchased, please contact Rational Software. * If you have licensing questions and problems and you can't find the solution in the License Key Administrator online Help, please contact Licensing Support. For contact information, look up "contacting" in the Rational License Key Administrator online Help index. * Quantify must be installed after Visual C++, Visual Basic, and Visual Test in order for it to install an integration with these tools. If you installed one of these tools after Quantify, simply re-install Quantify to get the integration. * Quantify can be installed as part of Rational Suite DevelopmentStudio. When you do a custom install of Rational Suite DevelopmentStudio, and you choose to install only Quantify, Rational Software Setup installs additional components that are not used by Quantify. For example, SQL Anywhere. * To uninstall a previous copy of Quantify, double-click the Add/Remove Programs icon in the Control Panel and uninstall Quantify. The uninstall program removes all of the files associated with the Quantify installation. If you do not do an uninstall, but instead install a new version of Quantify over the previous version, be sure to delete all files in the Quantify cache directory first. Your application and its modules must be reinstrumented after installation to operate correctly with the current release of Quantify. ----------------------------------------------------------------- 4. Notes ----------------------------------------------------------------- * When Quantify reports its results, it includes virtually no overhead. The numbers you see are the time your program would take without Quantify. * To monitor Visual C++ or Visual Basic controls, or Java applets, launched from Microsoft Internet Explorer 4.0 with the Active Desktop "shell integration" installed, you must specify the "-new" argument. You can specify "-new" in Command-line arguments in the Run Program dialog or from the command line. For example, to monitor controls or Java applets from the command line, type respectively: quantify iexplore.exe -new # to profile a control qstart iexplore.exe -new # to profile an applet The "-new" argument causes a new Iexplore.exe process to start and be instrumented (for Visual C++ and Visual Basic 5 only) before monitoring your control or applet. Without this argument, the control or applet is run by the current desktop explorer and no performance data is collected. * When you add Quantify to the Visual J++ 1.1 Tools menu and you open the class file as a project, you must specify $(ProjectName) $(ProjectArgs) in the Arguments list. * Quantify requires symbols in order to find the function names correctly. Functions for which there are no symbols are displayed with the name "UnnamedFunction" or, in the case of some timed COM functions, "UnnamedTimedFunction". By default, Quantify filters the "UnnamedFunction" functions from the current dataset but continues to distribute their time to their callers. To correctly display these functions, make the symbolic data available and then reinstrument and rerun the program. * Calls to Visual Basic built-in functions are often shown labeled with an "rtc" prefix. Calls to Visual Basic built-in controls and other ActiveX controls are shown as "UnnamedTimedProcedures" because no symbolic information is currently available to name these procedures. Argument types declared for Visual Basic procedures and subroutines are not encoded by the compiler and so are missing from Quantify's display. Names used in Declare statements for Win32 API aliases are not preserved by the compiler and thus are not presented by Quantify. However, in all cases, the time recorded is accurate and attributed to the proper lines in the annotated Visual Basic source code. * Online help is available by selecting Help > Help Topics or Help > Help Index. To access context-sensitive help for a command or a window or dialog control, click the help icon on the toolbar or in the dialog, and then click the control. You can also press F1 to display help for the control. ----------------------------------------------------------------- 5. Known problems ----------------------------------------------------------------- * Interaction with other applications * Instrumenting programs * Running programs * Working with performance data Interaction with other applications ----------------------------------- * There is a known problem with VC6 when migrating from VC5 where it leave a VC5 signature in the .pdb file when building from the command line. Quantify sees this file as corrupt and cannot read the symbols from it. To work around the problem, delete the .pdb file for the application and re-build. * Quantify does not work correctly when dlls are injected into a process via the AppInit_DLLs registry key because it fails to instrument the injected libraries. In order for Quantify to work correctly, the application which uses the key must be uninstalled and the system must be rebooted. The utility ComSpyNT is known to use this registry key. * Applying changes to a running Quantify'd program, using "Edit & Continue" in VC6 is not supported. * There are compatibility problems between Quantify and applications that use SetWindowsHook() and SetWindowsHookEx(). The SetWindowsHook() APIs are disabled in Quantify'd programs. This is to avoid hooking uninstrumented programs with Quantify'd DLLs. For workarounds to this, please contact Rational Software's Technical Support. [21155] * In rare instances, Quantify fails to find DLLs or OCXs required by LoadLibraries. Try adding the module's directory to your PATH environment variable. [34919] * You cannot use the stdin/stdout redirection request, as in test.exe < test.txt, when you instrument and run programs using the Run Program dialog. [00254, 23822, 33100] * In Quantify'd programs, argv[0] is set to the instrumented filename. You can specify a name for the instrumented file in the Settings for filename dialog (executable settings) if your program depends on a specific value for argv[0]. [00281] * Internet Explorer 3.02 creates many "fibers" during file transfers. This will cause a Quantify'd IE 3.02 to consume a lot of virtual memory. [36977] Instrumenting programs ---------------------- * If you copy a DLL that you want to instrument into your working directory, also copy any related .pdb, .dbg, or .map files. This ensures that Quantify's function names are as informative as possible. * If your executable was built with MSVC 5.0 or 6.0 with no relocations, Quantify will display a warning message and it will only report timed performance data for any exported functions in the executable, even if you have debug data. Avoid the use of the /FIXED linker option or specify /FIXED:NO. * Modules built from assembly code may not instrument correctly by default if they do not follow standard calling conventions. For assistance in such cases, contact Rational Software's Technical Support. * Quantify appends the instrumentation log to the _pure.log file in the same directory as the program executable. If an error occurs, the log may be in the _pure.tmp file. * Quantify will not reinstrument files in the following situations: * A .pdb file is supplied after a .dll or .exe file has been instrumented. When you rerun the program, Quantify does not reinstrument the .pdb file. * You swap two .dlls that have the same name and the same creation time, such as a debug version and a production version. The "new" .dll is not instrumented, because an identically-named file with the same timestamp already exists in the Quantify cache directory. In each case, you can work around the problem by deleting the instrumented files to force reinstrumentation. Running programs ---------------- * Quantify does not compute the correct machine speed on Windows NT 3.51 and on some non-Intel processors. In this case it will use the default of 100MHz. To alter this use /DefaultClockRate=166MHz, for example, to specify a clock rate of 166 MHz. * If you receive the following message, "Shared memory exhausted. Saving data and disabling collection.", your application may require more shared memory than Quantify has allocated by default. You can increase the size of this shared memory by using the option "-runtime-data-size=" (default value is 0x10000000). This can be set in the Additional Options field under the Run Program dialog > Settings > Files tab. * Quantify appends the runtime log to the file _pure.log in the same directory as the program executable. * On occasion, Quantify might experience an internal error. These errors would be displayed in the "Run Summary" window under the "Messages" tab as Quantify internal errors. Please follow the onscreen instructions and submit any Quantify internal errors you receive to Rational Software's Technical Support. Working with performance data ----------------------------- * Data set operations such as focus and delete subtree data can change F and F+D times or even eliminate certain functions that have annotated source. Currently all the data collected at line level is NOT changed during data set operations (it reflects the totals over the entire dataset). [32511] * For Visual Basic source files last edited with VB5.0sp1 or earlier (including the VB5 samples), a change in the VB compiler means that annotations in the annotated source file can be offset by as many as 7 lines. If this occurs, edit and save the file with a more recent version of VB5 or VB6 and rebuild your project. * In Visual Basic 6.0, multi-line statements using the underscore '_' line continuation character cause annotations in the annotated source file to be offset by a number of lines equal to the number of continuations present. ----------------------------------------------------------------- 6. Contacting Technical Support ----------------------------------------------------------------- If you have a technical problem and you can't find the solution in the online Help, you can contact Technical Support at: North America: Rational Software 18880 Homestead Road Cupertino, CA 95014 voice: (800)433-5444 fax: (408)863-4001 email: support@rational.com Europe and Middle East: Rational Software Beechavenue 30 1119 PV Schiphol-Rijk The Netherlands voice: +31 (0)20 454 6200 fax: +31 (0)20 454 6201 email: support@europe.rational.com Japan: Nihon Rational Software, SAISEI Ikedayama, Bldg. 2F, 5-10-25 Higashi-Gotanda, Shinagawa-ku, Tokyo 141-0022, Japan voice: 03-5423-3611 fax: 03-5423-3622 email: support@japan.rational.com Australia and Asia Pacific: Rational Software Corporation Pty Ltd, Zenith Centre, Level 13, 821 Pacific Highway, Chatswood NSW 2067, Australia voice: 02- 9419-0111 fax: 02- 9419-0123 email: support@apac.rational.com If you email, include the license information that appears in the "Help->About Rational Quantify" dialog along with the Quantify log file. Before you call: 1. Note the sequence of events that led to the problem and any program or error messages that you see. 2. Have your license key and customer number ready and, if possible, the product running on your computer. Note: * If you have licensing questions and problems and you can't find the solution in the License Key Administrator online Help, please contact Licensing Support. For contact information, look up "contacting" in the Rational License Key Administrator online Help index.