README.HTML
Copyright © 1997-2002 Rational Software Corporation. All rights reserved.
Rational, the Rational logo, Quantify, Rational Visual Test, Rational Robot, and ClearQuest are
trademarks or registered trademarks of Rational Software Corporation in the
United States and in other countries.
Visual C++, Windows, Windows NT, Developer Studio, Visual Studio, .Net and Microsoft are trademarks or
registered trademark 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 2002.05.20 for Windows
TABLE OF CONTENTS
-
What's new in Quantify?
-
Requirements
-
Installing Quantify
-
Notes
-
Known problems
-
Contacting Technical Support
Back to Top
1. What's new in Quantify?
New in Quantify 2002.05.20:
-
Quantify is now fully integrated with the Microsoft Visual Studio .NET IDE, enabling developers to
collect performance profiling data without having to leave the IDE. A standalone GUI is also
provided. Both managed and unmanaged code are supported but mixed mode applications can only collect
data for one type of component at a time. Debugging of managed code for which performance profiling
data is being collected is fully supported within the IDE.
-
Quantify now has the ability to instrument only a selected set of modules. In this special mode (referred
to in the online help as selective instrumentation), a user
chooses the modules to be instrumented and the remaining modules are untouched. Previously, if a user
was interested in a single .dll, they still had to instrument all modules, choosing the minimal mode
for everything except the module of interest. This mode can be beneficial for collecting data from an
addin to a large container program (such as Microsoft Visual Studio .NET) or native code being invoked
through the Java JNI interface. A user no longer needs to instrument all of msdev.exe or java.exe to get
the data they want.
-
Support has been added for Sun JDK1.4 (both the client and server versions).
-
A preview version of an ASP.NET profiling monitor (AspNetMon.exe) is included in this
release. This monitor enables Quantify profiling for managed code running in the context of ASP.NET
or as a Web Service.
The monitor is implemented as a Windows system tray icon. To start the monitor, first ensure that
the Quantify install directory (typically C:\Program Files\Rational\Quantify) is in the SYSTEM path,
then run AspNetMon.exe.
After the monitor is started, a small traffic light icon appears in the system tray area of the
Windows taskbar. The red light indicates profiling is disabled for all PurifyPlus products. The
green light indicates profiling is enabled for one of the products (Purify, Quantify, or Coverage).
Hover the mouse cursor over the monitor icon to view the current monitor status (enabled or disabled),
and the product name for which profiling is enabled (Purify, Quantify, or Coverage).
To change the monitor status, right-click the monitor icon in the system tray. A popup menu displays
the following choices:
- ASP.NET Monitoring Disabled
- Enable ASP.NET Monitoring for Quantify
- Enable ASP.NET Monitoring for Coverage
- Enable ASP.NET Monitoring for Purify
Choose "ASP.NET Monitoring Disabled" to disable profiling for all PurifyPlus products, or choose
"Enable ASP.NET Monitoring for " to enable profiling for one of the products.
Once started, the monitor will continue to run until the operating system is rebooted. To start the
monitor automatically, place a shortcut to AspNetMon.exe in the startup folder of the
All Users > Start Menu.
In order to obtain data for your ASP.NET application, you need to either take a snapshot from the
Quantify GUI or disable the monitor as described above.
New in Quantify 2002.05.00:
New in Quantify 2001A.04.00:
-
Quantify automatically detects all installed Java Virtual Machines that are identified in the
Windows registry. You can now choose from a list of the detected JVMs in the JVM tab
in the Settings > Preferences dialog.
-
Quantify now recognizes the JAVA_HOME user environment variable. If Quantify was unable to detect
the JVM you want to use for memory profiling, set JAVA_HOME to point to the JVM home
directory and Quantify will default to it.
-
Support has been added for "managed" applications in the Microsoft .Net platform.
Quantify supports applications running on .Net Beta 1. To collect performance
data for these applications, select the "Managed Code" radio button in the "Run Program"
dialog.
-
Quantify is integrated into the VS.Net shell. The Quantify menu item appears as usual
in the VS.Net IDE, however the toolbar is hidden.
-
Support has been added for reading and displaying performance trace data formatted in XML.
See XMLTrcReader.html in the Quantify installation directory for details.
-
The Quantify Interpreter Interface is now publicly available. This set of APIs can be used
by third party language vendors for gathering performance data from their applications and displaying
the results in the Quantify GUI. See QProf.html in the Quantify installation directory for details.
-
Sun JDK1.3 support has been enhanced to eliminate the manual steps described in the notes
for Quantify 2001.03.00.
New in Quantify 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:
-
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";
};
-
Copy PureJVMPI.dll into %JAVA_ROOT%\jre\lib\ext\x86 folder
-
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).
-
Make sure that Rational.jar is copied into %JAVA_ROOT%\jre\ext folder and you
have this folder in your CLASSPATH environment variable.
-
Start your applet. Use qstart or set
_JAVA_OPTIONS=-XrunPureJVMPI:Quantify
New in Quantify 2000.02.10:
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.
Back to Top
2. Requirements
-
PC-compatible Pentium system or above, Intel architecture
-
One of the following Operating Systems
- Microsoft Windows NT 4.0 with Service Pack 6a or greater
- Microsoft Windows 2000
- Microsoft Windows XP Professional
-
64 Mb RAM required, 256Mb 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.
-
Quantify for Windows supports:
|
Architecture:
|
Win32 programs only
|
|
Compilers:
|
Microsoft Visual C++ 6.0, including the Visual C++ 6.0 Processor Pack
Microsoft Visual C++ .NET
Microsoft Visual Basic 6.0sp3
|
|
Interpreters:
|
Microsoft Visual Basic 6.0sp3
Microsoft virtual machine for Java.
The version for Msjava.dll should be 2828 or later. The
latest release of the virtual machine and SDK is available at:
http://www.microsoft.com/java/download.htm
Sun JVM 1.2.2 and higher.
When running on the Pentium 4 with JDK 1.2.2, build 007 is required. Previous versions
of 1.2.2 will not run on Pentium 4.
|
|
Debuggers:
|
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.
|
Back to Top
3. Installing Quantify
To install Quantify:
-
Verify that your swap space is set to at least 200Mb, the minimum recommended.
-
Run Setup.exe and follow the onscreen instructions.
Notes:
-
You are installing a licensed Rational Software product. The product you have
purchased includes a node-locked, named-user 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, named-user 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.
Back to Top
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.
Back to Top
5. Known problems
Interaction with other applications
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 <executable>_pure.log
file in the same directory as the program executable. If an error occurs, the
log may be in the <executable>_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.
-
Instrumented .dll and .exe files that are located
outside of the Quantify cache directory are not
deleted when you install a new version of Quantify.
When you run a program that uses one of those
files, Quantify uses the existing instrumented version.
In each case, you can work around the problem by deleting
the instrumented files to force reinstrumentation.
Running programs
-
When profiling native code invoked through Java's JNI interface, the Java runtime may throw an
exception and abort. This is a known problem that can be worked around by specifying the
Quantify option /profiler-runtime-flags=4 when instrumenting the native code. This may cause the
Descendant time for functions that return back through JNI to appear larger than normal. The function
time, however, will still be correct.
-
Due to a synchronization problem within the Japanese Language Pack on Windows XP, Quantify
must change the default keyboard setting for instrumented programs from Japanese to English. Before
doing this, a dialog box will be displayed requesting consent to do so.
-
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
<executable>_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.
Back to Top
6. Contacting Technical Support
If you have a technical problem and you can't find the solution
in online Help, you can contact Technical Support.
The Americas:
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
Australia and Asia Pacific:
Rational Software Corporation Pty Ltd,
Zenith Centre, Level 13,
821 Pacific Highway,
Chatswood NSW 2067,
Australia
voice: +61 02-9419-0111
fax: +61 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:
-
Note the sequence of events that led to the problem
and any program messages or error view messages displayed.
-
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.
Back to Top