Command-line Options (Performance Profiling)

Related Topics

This section lists the options you can use when you profile programs from the command line.

Command-line option conventions:

§          If a yes or no option is specified and a value is not explicitly given, Quantify assumes the value to be yes.

§          Most options have equivalents in Quantify dialog boxes, or can be specified in Additional options in the Files tab in the settings dialog boxes. Options that should only be used in the command line are indicated in the list below with an asterisk (*).

§          Options you specify in the command line override settings that were saved from the Quantify user interface.

§          Most options you specify in the command line apply only to the current run of the program; they are not saved, and will not subsequently appear in the user interface. Options that are saved and applied to future runs of the program, either from the command line or the user interface, are identified in the descriptions of the options.

§    For command-line option syntax, click images\shortcut.gif

 

/AllowDialogOnAssert

/CacheDir

/ClassInstrumentationType *

/CollectionGranularity

/ExeIniFileName *

/FilterFiles *

/Help *

/LabelThreadsWithSystemIDs

/net *

/Out

/PrintInstallDir *

/QuantifyClassesExcludeMust *

/QuantifyClassesIncludeMust *

/QuantifyDefaultInstrumentationType

/QuantifyExcludeMust

/QuantifyFunctionMust

/QuantifyLineMust

/QuantifyTimedMust

/Replace *

/Run *

/RuntimeDataSize

/SaveData *

/SaveTextData *

/SelectedModuleList *

/SelectiveInstrumentation *

/ShowInstrumentationProgress *

/ShowLoadLibraryProgress *

/SourcePath

/TimeSystemDir

/UndoModuleList *

/UndoReplace *

/UndoSelective *

/Usage *

/Version *

/? *

filename.qfy *

 

/AllowDialogOnAssert=yes|no

Specifies whether to allow the Assert dialog box to be displayed for program execution errors. For example:

quantify /AllowDialogOnAssert myapp.exe

By default, the Assert dialog box is not displayed.

 

/CacheDir=<directory>

Specifies the directory you want to use to store instrumented versions of native-compiled (unmanaged) executable and module files. For example:

quantify /CacheDir="C:\Program Files\Rational\PurifyPlus\Cache" myapp.exe

By default, cached files are stored in the PurifyPlus cache directory.

§      This option does not apply when you are using the /SelectiveInstrumentation option.

§      This option is valid only for native-code (unmanaged) programs.

 

/ClassInstrumentationType=all | selective

Specifies whether to include or exclude specific .NET classes at runtime. Use this option together with the /QuantifyClassesIncludeMust or /QuantifyClassesExcludeMust option.

Quantify instruments and collects data for classes as follows:

all

Directs Quantify to exclude .NET classes matching a pattern specified in /QuantifyClassesExcludeMust. All other classes will be included..

selective

Directs Quantify to include .NET classes matching a pattern specified in /QuantifyClassesIncludeMust. All other classes will be excluded..

For example:

quantify /QuantifyClassesExcludeMust=myClass.*;*.myInnerClass.* /ClassInstrumentationType=all /SaveData /net Myapp.exe arg1

Quantify instruments and collects data for all classes except classes whose fully qualified name begins with the string myClass., or has the string .myInnerClass. embedded in it.

§      Command line only option.

 

/CollectionGranularity=line | function | time
or
/QuantifyDefaultInstrumentationType=line | function | time

Specifies the type of measurement (line, function, or time) you want Quantify to use to collect data. The measurement type applies to all modules in the program (except those in the Windows directories, to which the /TimeSystemDir option can apply). For example:

quantify /CollectionGranularity=line myapp.exe

or

quantify /QuantifyDefaultInstrumentationType=function myapp.exe

By default, Quantify uses line for all modules with debug data, and times all others and those in the Windows directories. For more information about Quantify's measurement types, click images\shortcut.gif.

§      This option does not apply when you are using the /SelectiveInstrumentation option.

 

/ExeIniFileName=<filename>

Specifies the name of an INI file containing runtime options and settings you want Quantify to use for the program run. For example:

quantify /SaveTextData /ExeIniFileName=myapp_options.ini /net myapp.exe

Quantify profiles Myapp.exe using the runtime options and settings contained in myapp_options.ini, and saves the analysis data to a text file.

§      Command line only option.

 

/FilterFiles=<filename1.qft;filename2.qft;filename3.qft...>

When you are saving data to a text file, specifies the Quantify filter files (.qft) you want Quantify to use to filter data from the output text file. For example:

quantify /SaveTextData /FilterFiles=myapp_exe.qft;D:\testapp\testapp_exe.qft myapp.exe

Quantify profiles Myapp.exe, and uses the filter files Myapp_exe.qft and Testapp_exe.qft to filter the analysis data that it writes to a text file.

§      Command line only option.

 

/Help

Displays the syntax for command-line options.

§      Command line only option.

 

/LabelThreadsWithSystemIDs=yes|no

Specifies whether Quantify appends system-generated thread IDs to thread labels.

Quantify /LabelThreadsWithSystemIDs=yes

By default, Quantify uses ordinal numbers in thread labels. For example; .<StartFunctionName>_<OrdinalNumber>., or .thread_<OrdinalNumber>., where <OrdinalNumber> is a sequence number that is incremented for each new instance of a thread.

Since system-generated thread IDs can vary between runs, Quantify may not be able to match identical threads when you compare runs. To ensure that identical threads are correctly compared, use the Rename Thread dialog box in the Quantify main window, or the QuantifySetThreadName API function in your program code to assign specific names to threads.

 

/net

Specifies that the program you want to profile is a .NET managed code program, or a Visual Basic p-code program.

§      This option does not apply when you are using the /SelectiveInstrumentation option.

§      Command line only option.

 

/Out=<path>

Specifies the path you want Quantify to use for the instrumented version of a native-compiled (unmanaged) program.

If you specify a relative path, Quantify stores the instrumented executable in a path relative to the current working directory. For this command-line option, this is the directory you were in when you typed the command. For example, if you type the following at the command line:

D:
cd \Win32app
quantify /Out=Cache\Foo_pure.exe C:\Myapp\Bar.exe

Quantify instruments C:\Myapp\Bar.exe, names the instrumented version Foo_pure.exe, and stores the instrumented version in D:\Win32app\Cache.

By default, Quantify uses the encoded path of the original file and other information to name instrumented files, and stores them in its cache directory.

§      This option does not apply when you are using the /SelectiveInstrumentation option.

§      This option is valid only for native-code (unmanaged) programs.

 

/PrintInstallDir

Displays the directory where you installed Quantify.

§      Command line only option.

 

/QuantifyClassesExcludeMust=<pattern1;pattern2;pattern3...>

Selects .NET classes to exclude from memory profiling. Quantify collects memory profiling data for all classes except classes whose fully qualified name contains a character string that matches a value in the argument list.

To use /QuantifyClassesExcludeMust, you must also specify /ClassInstrumentationType=all. For example:

quantify /QuantifyClassesExcludeMust=myClass.*;*.myInnerClass.* /ClassInstrumentationType=all /SaveData /net MyApp.exe arg1

Pattern string matching is case-sensitive.

Use an asterisk (*) to denote any character string; use a backslash (\) with the asterisk if the name itself contains an asterisk. For example:

This pattern

Matches any class whose name

MyApp*

Begins with MyApp and is followed by any string

*chr

Starts with any string and ends in chr

*font*

Contains font

delete(void\**

Is delete and whose first argument is void*

 

/QuantifyClassesIncludeMust=<pattern1;pattern2;pattern3...>

Selects .NET classes to profile. Quantify collects memory profiling data for only those classes whose fully qualified name contains a character string that matches a value in the argument list. All other classes are excluded.

To use /QuantifyClassesIncludeMust, you must also specify /ClassInstrumentationType=selective. For example:

quantify /QuantifyClassesIncludeMust=myClass.*;*.myInnerClass.* /ClassInstrumentationType=selected /SaveData /net MyApp.exe arg1

Pattern string matching is case-sensitive.

Use an asterisk (*) to denote any character string; use a backslash (\) with the asterisk if the name itself contains an asterisk. For example:

This pattern

Matches any class whose name

MyApp*

Begins with MyApp and is followed by any string

*chr

Starts with any string and ends in chr

*font*

Contains font

delete(void\**

Is delete and whose first argument is void*

 

/QuantifyExcludeMust=<module1;module2;module3...>

Specifies modules that you want Quantify to exclude from measurement. Use this option only when the program you're profiling malfunctions as a result of a DLL being injected into it by another process calling SetWindowsHook(). Typical examples of "hook DLLs" that need to be excluded are special mouse and glidepad drivers. For example:

quantify /QuantifyExcludeMust=intellimouse.dll myapp.exe

Quantify does not record time spent in functions in an excluded DLL; if this time is significant, the resulting performance data can be misleading. By default, Quantify excludes all "hook DLLs" known at time of shipping. If you find a new DLL that needs to be excluded, please notify Rational Software Technical Support. For more information on contacting Technical Support, click images\shortcut.gif

§      This option does not apply when you are using the /SelectiveInstrumentation option.

§      This option is valid only for native-code (unmanaged) programs.

 

/QuantifyFunctionMust=<module1;module2;module3...>

Specifies program modules you want Quantify to measure at function level. For example:

quantify /QuantifyFunctionMust=my_other.dll;myapp.dll myapp.exe

By default, Quantify measures modules using the default measurement type specified in the /QuantifyDefaultInstrumentationType option (except for functions in system modules and in modules located in the Windows directories, which are always timed). For more information about how Quantify measures modules, click images\shortcut.gif

§      This option does not apply when you are using the /SelectiveInstrumentation option.

§      This option is valid only for native-code (unmanaged) programs.

 

/QuantifyLineMust=<module1;module2;module3...>

Specifies program modules you want Quantify to measure at line level. For example:

quantify /QuantifyLineMust=my_other.dll;myapp.dll myapp.exe

By default, Quantify measures modules using the default measurement type specified in the /QuantifyDefaultInstrumentationType option (except for functions in system modules and in modules located in the Windows directories, which are always timed). For more information about how Quantify measures modules, click images\shortcut.gif

§      This option does not apply when you are using the /SelectiveInstrumentation option.

§      This option is valid only for native-code (unmanaged) programs.

 

/QuantifyTimedMust=<module1;module2;module3...>

Specifies modules whose functions you want Quantify to time. For example:

quantify /QuantifyTimedMust=my_other.dll;myapp.dll myapp.exe

By default, Quantify measures modules using the default measurement type specified in the /QuantifyDefaultInstrumentationType option (except for functions in system modules and in modules located in the Windows directories, which are always timed). For more information about how Quantify measures modules, click images\shortcut.gif

§      This option does not apply when you are using the /SelectiveInstrumentation option.

§      This option is valid only for native-code (unmanaged) programs.

 

/Replace=no | yes

Specifies whether to instrument and run the executable in place, rather than storing the instrumented version in the cache directory. Before instrumenting the executable, a backup copy is created (Exename.exe.original) and saved in the same directory as the original executable.

Use this option to run a test script or batch file using the instrumented program. For example:

quantify /Replace=yes myapp.exe

By default, Quantify does not replace the executable, but instead stores the instrumented executable in the cache directory.

If you are using Microsoft Windows 2000 or higher, the Windows File Protection feature (WFP) may prevent certain types of files from being replaced. For a workaround to this problem, click images\shortcut.gif.

§      This option does not apply when you are using the /SelectiveInstrumentation option.

§      This option is valid only for native-code (unmanaged) programs.

§      Command line only option.

 

/Run=no | yes

Specifies whether to instrument a program or module without running it. For example:

quantify /Run=no myapp.exe

By default, Quantify runs the instrumented executable.

You can create a log file that contains instrumentation information by typing:

quantify /Run=no myapp.exe 2>logfile.txt

Since options you specify in the command line apply only to the current run of the program and are not saved, Quantify may generate a warning in certain situations. For example:

quantify /Run=no /TimeSystemDir=no myapp.exe

In this example, Quantify instruments the C runtime library used by myapp.exe. Myapp.exe loads a dll called mydll.dll which also uses the C runtime library. So, if you open the instrumented myapp.exe directly, the instrumented C runtime library is loaded when the program runs. Then when myapp.exe uses LoadLibrary to load mydll.dll, Quantify will try to reinstrument the C runtime library using the timed instrumentation type (as the /TimeSystemDir=no on the command line is not applied to this run). Since the C runtime is already loaded, Quantify issues the warning: "Could not reinstrument C:\Windows\System32\\MSVCRTD.DLL as requested: Access is denied."

 

§      This option is valid only for native-code (unmanaged) programs.

§      Command line only option.

 

/RuntimeDataSize=<size>

Sets the size of the shared memory that Quantify allocates to store the data it collects at run time. You can specify the size in hexadecimal or decimal format. For example:

quantify /RuntimeDataSize=0x20000000 myapp.exe

By default, Quantify uses a size of 0x10000000.

 

/SaveData[=<filename.qfy>]

Saves the data to a Quantify data file (.qfy) without displaying any Quantify windows. For example:

quantify /SaveData=myapp1.qfy myapp.exe

If you do not specify a file name, Quantify uses <exename>.qfy and saves the file in the same location as your program.

If an identically named file already exists, Quantify overwrites the file. You can modify this behavior by adding a filename format specifier: see Specifying unique filenames when saving files

 

You can use this command with the /SaveTextData command to generate both a Quantify data file and an ASCII text file. This is useful when you want a .qfy file to analyze using the Quantify user interface and a text file that a script can parse.

§      Command line only option.

 

/SaveTextData[=<filename.txt>]

Saves the data to an ASCII text file (.txt) without displaying any Quantify windows. For example:

quantify /SaveTextData=myapp1.txt myapp.exe

If you do not specify a file name, Quantify uses <exename>.txt and saves the file in the same location as your program.

If an identically named file already exists, Quantify overwrites the file. You can modify this behavior by adding a filename format specifier: see Specifying unique filenames when saving files

You can use this command together with the /SaveData command to generate both an ASCII text file and a Quantify data file. This is useful when you want a text file that a script can parse, and a .qfy file to analyze using the Quantify user interface.

 

§      Command line only option.

 

/SelectedModuleList=<module1[,T|P|N][,L|F];module2[,T|P|N][,L|F];...>

Specifies modules you want Quantify to instrument using selective instrumentation, and the instrumentation state and measurement type for each module. Separate multiple modules with semicolons.

When you use the /SelectedModuleList option, you must also specify the /SelectiveInstrumentation option. For example:

quantify /SelectiveInstrumentation /SelectedModuleList=my_other.dll,T,F;myapp.dll myapp.exe

Quantify runs myapp.exe, but it collects performance data only for my_other.dll and myapp.dll.

You can specify two positional options, separated by commas, after each module name:

1.    instrumentation state: T (transient state, the default), or P (permanent state), or N (none, the module is not instrumented)

2.    measurement type: L (line), or F (function)

All selected modules must have debug data, and .exes must also have relocation data.

§      This option is valid only for native-code (unmanaged) programs.

§      Command line only option.

 

/SelectiveInstrumentation=no | yes

Specifies whether you want to use selective instrumentation to instrument and collect performance data only for modules you specify using the /SelectedModuleList option. For example:

quantify /SelectiveInstrumentation /SelectedModuleList=my_other.dll;myapp.dll myapp.exe

Quantify runs myapp.exe, but it collects data only for my_other.dll and myapp.dll.

By default, Quantify instruments and collects data for your program and all modules your program calls.

To use selective instrumentation, selected modules must have debug data, and .exes must also have relocation data.

§      This option is valid only for native-code (unmanaged) programs.

§      Command line only option.

 

 

/ShowInstrumentationProgress=no | yes

Specifies whether to display the Instrumenting dialog box, showing Quantify's progress as it instruments files. For example:

quantify /ShowInstrumentationProgress=no myapp.exe

By default, Quantify shows the dialog box.

§      This option is valid only for native-code (unmanaged) programs.

§      Command line only option.

 

/ShowLoadLibraryProgress=no | yes

Specifies whether to display the Instrumenting dialog box when Quantify instruments files required by calls to LoadLibrary. For example:

quantify /ShowLoadLibraryProgress=no myapp.exe

By default, Quantify shows the dialog box.

§      This option is valid only for native-code (unmanaged) programs.

§      This option does not apply when you are using the /SelectiveInstrumentation option.

§      Command line only option.

 

/SourcePath=<search path>

Specifies the search path to use to locate source files to display in the Annotated Source window. You can specify multiple paths by separating them with semicolons. For example:

quantify /SourcePath="D:\app\src;C:\thirdpartylibs\db\src" myapp.exe

By default, Quantify uses the following search order to locate source files:

1.    The directory where the program you're profiling is located.

2.    The search path specified in the Files tab of the Settings for exename dialog box.

3.    The directories specified in the Visual Studio Workspace file.

4.    The search path specified in the Files tab of the Default Settings dialog box.

5.    The MFC and Visual C++ directories.

6.    The PATH environment variable.

Annotated source code is available only if debug data was available and if a module was measured at line level. Annotated source code showing line-by-line performance data is not available when profiling Visual Basic 6.0 p-code programs.

 

/TimeSystemDir=yes | no

Specifies whether to time all modules in the Windows directories for programs. For example:

quantify /TimeSystemDir=no myapp.exe

By default, Quantify times these modules.

§      This option does not apply when you are using the /SelectiveInstrumentation option.

§      This option is valid only for native-code (unmanaged) programs.

 

/UndoModuleList=<module1;module2;...>

Specifies previously instrumented modules that you want to restore to their original, uninstrumented state. Separate multiple modules with semicolons.

Use this option together with:

§    /UndoReplace: to restore specific modules that you instrumented using the /Replace option. For example:

Quantify /UndoReplace /UndoModuleList=myapp.exe

§    /UndoSelective: to change the instrumentation state of modules you instrumented using selective instrumentation, to the None state. For example:

Quantify /UndoSelective /UndoModuleList=my_other.dll;myapp.dll

Quantify restores the original, uninstrumented versions of my_other.dll and myapp.dll, and changes the instrumentation state to None.

§      This option is valid only for native-code (unmanaged) programs.

§      Command line only option.

 

/UndoReplace

Restores all modules that you instrumented using the /Replace option to their original, uninstrumented state. For example:

Quantify /UndoReplace

You can use this option together with the /UndoModuleList option to restore specific modules.

§      This option is valid only for native-code (unmanaged) programs.

§      Command line only option.

 

/UndoSelective

Restores the original, uninstrumented versions of all modules you instrumented using selective instrumentation, and changes the instrumentation state to None. For example:

Quantify /UndoSelective

You can use this option together with the /UndoModuleList option to restore and change the instrumentation state of specific modules.

§      This option is valid only for native-code (unmanaged) programs.

§      Command line only option.

 

/Usage

Displays the syntax for command-line options.

§      Command line only option.

 

/Version

Displays version information about the current Quantify installation.

§      Command line only option.

 

/?

Displays the syntax for command-line options.

§      Command line only option.

 

filename.qfy

Displays a previously saved Quantify data file (.qfy). For example:

quantify myapp.qfy

§      Command line only option.

Syntax Notes:

§      Any Quantify options you specify must precede the name of the executable. Quantify interprets anything after the name of the executable as an argument passed to the program.

§      You must place quotation marks around strings with embedded spaces. For example:
/CacheDir="C:\Program Files\My Net Tests\Cache"

§      You must precede option names with a slash (/) or hyphen (-), and use an equal sign (=) to specify an option value.

§      Command-line options in the online Help are always shown in mixed case. However, Quantify ignores the case and any hyphens or underscores in the option name. For example, the option /TimeSystemDir is equivalent to /TIME_SYSTEM_DIR, -TimeSystemDir, and /time-system-dir.

(C) Copyright IBM Corporation 1993, 2009.