This section lists the options you can use when you monitor programs from the command line.
Command-line option conventions:
§ If a yes or no option is specified and a value is not explicitly given, PureCoverage assumes the value to be yes.
§ Most options have equivalents in PureCoverage dialog boxes, or can be specified in Additional options in the Files tab in the settings dialog boxes. Options that can be set only in the command line are indicated in the list below with an asterisk (*).
§ Options you specify in the command line override any settings that were saved from the PureCoverage 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
/CoverageDefaultInstrumentationType
/Help *
/java *
/net *
/Replace *
/Run *
/ShowInstrumentationProgress *
/Usage *
/Version *
/? *
<filename>.cfy or <filename>.pcy *
/ActiveMerge = yes | no
Specifies whether PureCoverage uses the ActiveMerge feature when it creates an Auto Merge for the program run. ActiveMerge lets you select and evaluate the contributions of individual layers in a merged run.
For example:
coverage /ActiveMerge=yes /SaveMergeData myapp.exe
By default, PureCoverage creates Auto Merge runs without applying the ActiveMerge feature.
§ Command line only option.
/AllowDialogOnAssert=yes|no
Specifies whether to allow the Assert dialog box to be displayed for program execution errors. For example:
coverage /AllowDialogOnAssert myapp.exe
By default, the Assert dialog box is not displayed.
/AutoMergeData = yes | no
Specifies whether PureCoverage creates an Auto Merge run when you monitor a program, and automatically updates the run with data from subsequent runs of the program. For example:
coverage /AutoMergeData=no myapp.exe
By default, PureCoverage creates an Auto Merge run and appends the run with data from subsequent runs of the program.
Note: If you specify /AutoMergeData=no with the /SaveMergeData option, PureCoverage creates an Auto Merge run and saves the data to a PureCoverage data file (.cfy). If an identically named .cfy file already exists, Purify automatically overwrites the file. This effectively writes single run data to the <exename>_AutoMerge.cfy>
§ Command line only option.
/CacheDir=<directory>
Specifies the directory you want to use to store instrumented versions of Visual C++ executable and module files. For example:
coverage /CacheDir="C:\Program Files\IBM\RationalPurifyPlus\Cache" myapp.exe
By default, PureCoverage uses the PurifyPlus cache directory.
§ This option is valid only for native-code (unmanaged) programs.
§ This option does not apply when you are using the /SelectiveInstrumentation option.
/ClassInstrumentationType=all | selective
Specifies whether to include or exclude specific Java or .NET classes at runtime. Use this option together with the /CoverageClassesIncludeMust or /CoverageClassesExcludeMust option.
PureCoverage instruments and collects data for classes as follows:
all |
Directs PureCoverage to exclude java or .NET classes matching a pattern specified in /CoverageClassesExcludeMust. All other classes will be included.. |
selective |
Directs PureCoverage to include java or .NET classes matching a pattern specified in /CoverageClassesIncludeMust. All other classes will be excluded.. |
For example:
coverage /CoverageClassesExcludeMust=myClass.*;*.myInnerClass.* /ClassInstrumentationType=all /SaveData /java java.exe myapp.class
PureCoverage 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.
/CoverageClassesExcludeMust=<pattern1;pattern2;pattern3...>
Selects Java or .NET classes to exclude from coverage monitoring. PureCoverage collects coverage data for all classes except classes whose fully qualified name contains a character string that matches a value in the argument list.
To use /CoverageClassesExcludeMust, you must also specify /ClassInstrumentationType=all. For example:
coverage /CoverageClassesExcludeMust=myClass.*;*.myInnerClass.* /ClassInstrumentationType=all /SaveData /java java.exe myapp.class
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 |
JVM* |
Begins with JVM 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* |
/CoverageClassesIncludeMust=<pattern1;pattern2;pattern3...>
Selects Java or .NET classes to monitor. PureCoverage collects coverage 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 /CoverageClassesIncludeMust, you must also specify /ClassInstrumentationType=selective. For example:
coverage /CoverageClassesIncludeMust=myClass.*;*.myInnerClass.* /ClassInstrumentationType=selected /SaveData /java java.exe myapp.class
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 |
JVM* |
Begins with JVM 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* |
/CollectionGranularity=line | function | exclude
or
/CoverageDefaultInstrumentationType=line | function | exclude
Specifies the level of coverage (line, function, or exclude) you want PureCoverage to use when collecting data. The coverage level applies to all modules in the program (except those in the Windows directories, to which the /ExcludeSystemDir option can apply). For example:
coverage /CollectionGranularity=function myapp.exe
or
coverage /CoverageDefaultInstrumentationType=function myapp.exe
By default, PureCoverage uses line for all modules with debug data, and excludes all others and those in the Windows directories. However, if debug line information is not available for a module, PureCoverage excludes the module, instead of using line. For more information about PureCoverage's coverage levels, click
§ This option does not apply when you are using the /SelectiveInstrumentation option.
/CoverageExcludeMust=<module1;module2;module3;...>
Specifies modules that you want PureCoverage to exclude from coverage. PureCoverage does not record coverage data for excluded modules, and the modules do not appear in any data coverage windows. Use this option when the program you're monitoring 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:
coverage /CoverageExcludeMust=intellimouse.dll myapp.exe
By default, PureCoverage 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
§ This option is valid only for native-code (unmanaged) programs.
§ This option does not apply when you are using the /SelectiveInstrumentation option.
/CoverageFunctionMust=<module1;module2;module3;...>
Specifies Visual C++ program modules you want PureCoverage to monitor at function level. For example:
coverage /CoverageFunctionMust=my_other.dll;myapp.dll myapp.exe
By default, PureCoverage monitors modules using the default coverage level specified in the /CoverageDefaultInstrumentationType option (except for functions in system modules and in modules located in the Windows directories, which are always excluded). For more information about how PureCoverage monitors modules, click
§ This option is valid only for native-code (unmanaged) programs.
§ This option does not apply when you are using the /SelectiveInstrumentation option.
/CoverageLineMust=<module1;module2;module3;...>
Specifies Visual C++ program modules you want PureCoverage to monitor at line level. For example:
coverage /CoverageLineMust=my_other.dll;myapp.dll myapp.exe
By default, PureCoverage monitors modules using the default coverage level specified in the /CoverageDefaultInstrumentationType option (except for functions in system modules and in modules located in the Windows directories, which are always excluded). For more information about how PureCoverage monitors modules, click
§ This option is valid only for native-code (unmanaged) programs.
§ This option does not apply when you are using the /SelectiveInstrumentation option.
/ExcludeSystemDir=yes | no
Specifies whether to exclude all modules in the Windows directories. For example:
coverage /ExcludeSystemDir=no myapp.exe
By default, PureCoverage excludes these modules and does not collect any coverage data.
§ This option is valid only for native-code (unmanaged) programs.
§ 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 PureCoverage to use for the program run. For example:
coverage /SaveTextData /ExeIniFileName=myapp_options.ini /java myapp.class
PureCoverage profiles Myapp.class 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>.cft[;<filename2>.cft;<filename3>.cft...]
When you are saving data to a text file, specifies the PureCoverage filter files (.cft) you want PureCoverage to use to filter data from the output text file. To specify multiple files, separate them with semicolons. For example:
coverage /SaveTextData /FilterFiles=myapp_exe.cft;C:\testapp\testapp_exe.cft myapp.exe
PureCoverage monitors Myapp.exe, and uses the filter files Myapp_exe.cft and Testapp_exe.cft 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.
/java
Specifies that the program you want to monitor is a java program.
§ This option does not apply when you are using the /SelectiveInstrumentation option.
§ Command line only option.
/MergeFileList=<filename1;filename2;...>
Specifies a list of .cfy files that you want PureCoverage to merge to a file that you specify using the /SaveMergeData or /SaveMergeTextData option. For example:
coverage /MergeFileList=myapp1.cfy;myapp2.cfy /SaveMergeData=myapp_usermerge.cfy myapp.exe
If you do not specify a file name with /SaveMergeData or /SaveMergeTextData, PureCoverage uses <exename>_UserMerge.cfy or <exename>_UserMerge.txt and saves the file in the same location as your program.
If you specify this option with the /ActiveMerge=yes option, PureCoverage saves the merged files as an ActiveMerge dataset.
Note: If an identically named .cfy or .txt file already exists, PureCoverage automatically overwrites the file.
/MergeMaster=<filename.txt>
Specifies a text file containing .cfy filenames that you want PureCoverage to merge to a file that you specify using the /SaveMergeData or /SaveMergeTextData option. For example:
coverage /MergeMaster=myapp_list.txt /SaveMergeData=myapp_usermerge.cfy myapp.exe
By default, PureCoverage uses <exename>_UserMerge.cfy, or <exename>_UserMerge.txt.
Filenames in the MergeMaster text file must each appear on a separate line, followed by a carriage return line-feed.
If you specify this option with the /ActiveMerge=yes option, PureCoverage saves the merged files as an ActiveMerge dataset.
Note: If an identically named .cfy or .txt file already exists, PureCoverage automatically overwrites the file.
/net
Specifies that the program you want to monitor is a .NET managed 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 PureCoverage to use for the instrumented version of a Visual C++ program.
If you specify a relative path, PureCoverage 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
coverage /Out=Cache\Foo_pure.exe C:\Myapp\Bar.exe
PureCoverage instruments C:\Myapp\Bar.exe, names the instrumented version Foo_pure.exe, and stores the instrumented version in D:\Win32app\Cache.
By default, PureCoverage uses the encoded path of the original file and other information to name instrumented files, and stores them in its cache directory. If you specify a file name for the instrumented version of the program, it cannot be the same name as the original program. Use the /Replace option to rename the original program to <exename>.exe.original and replace it with the instrumented version.
§ This option is valid only for native-code (unmanaged) programs.
§ This option does not apply when you are using the /SelectiveInstrumentation option.
/PrintInstallDir
Displays the directory where you installed PureCoverage.
§ Command line only option.
/Replace=no | yes
Specifies whether to rename the Visual C++ executable you're monitoring to <exename>.exe.original, and name the instrumented version to <exename>.exe. This option is especially useful when you want to run a test script or batch file using the instrumented program. For example:
coverage /Replace=yes myapp.exe
By default, PureCoverage saves 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 .
§ 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.
/Run=no | yes
Specifies whether to instrument a Visual C++ program or module without running it. For example:
coverage /Run=no myapp.exe
By default, PureCoverage runs the instrumented executable.
You can create a log file that contains instrumentation information by typing:
coverage /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, PureCoverage may generate a warning in certain situations. For example:
coverage /Run=no /ExcludeSystemDir=no myapp.exe
In this example, PureCoverage 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, PureCoverage will try to reinstrument the C runtime library so as to exclude the files in the system directory (as the /ExcludeSystemDir=no on the command line is not applied to this run). Since the C runtime is already loaded, PureCoverage 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 PureCoverage allocates to store the data it collects at run time. You can specify the size in hexadecimal or decimal format. For example:
coverage /RuntimeDataSize=0x20000000 myapp.exe
By default, PureCoverage uses a size of 0x04000000(64MB).
/SaveData[=<filename>.cfy]
Saves data to a PureCoverage data file (.cfy) without displaying any PureCoverage windows. For example:
coverage /SaveData=myapp1.cfy myapp.exe
If you do not specify a file name, PureCoverage uses <exename>.cfy and saves the file in the same location as your program.
If an identically named file already exists, PureCoverage automatically 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 PureCoverage data file and an ASCII text file. This is useful when you want a .cfy file to analyze using the PureCoverage user interface and a text file that a script can parse.
§ Command line only option.
/SaveMergeData[=<filename>_AutoMerge.cfy]
Saves the Auto Merge data to a PureCoverage data file (.cfy) without displaying any PureCoverage windows. For example:
coverage /SaveMergeData=myapp1_automerge.cfy myapp.exe
If you do not specify a file name, PureCoverage uses <exename>_AutoMerge.cfy and saves the file in the same location as your program.
If an identically named file already exists, PureCoverage automatically merges the new run information into the existing file. You can modify this behavior by adding a filename format specifier: see Specifying unique filenames when saving files
If you specify this option with the /ActiveMerge=yes option, PureCoverage saves the merged data as an ActiveMerge dataset.
Note: If you specify /AutoMergeData=no with the /SaveMergeData option, PureCoverage creates an Auto Merge run and saves the data to a PureCoverage data file (.cfy). If an identically named .cfy file already exists, Purify automatically overwrites the file. This effectively writes single run data to the <exename>_AutoMerge.cfy>
file (or overwrites it if it already exists).
§ Command line only option.
/SaveMergeTextData[=<filename>_AutoMerge.txt]
Saves the merge data to an ASCII text file (.txt) without displaying any PureCoverage windows. For example:
coverage /SaveMergeData /SaveMergeTextData=myapp1_automerge.txt myapp.exe
If you do not specify a file name, PureCoverage uses <exename>_AutoMerge.txt and saves the file in the same location as your program.
If an identically named file already exists, PureCoverage overwrites the file. You can modify this behavior by adding a filename format specifier: see Specifying unique filenames when saving files
If you specify this option with the /ActiveMerge=yes option, PureCoverage saves the merged data as an ActiveMerge dataset.
Note: To save a text file with coverage data from the current run, and subsequent runs of the program, you must use the /SaveMergeData option with this option. If you do not specify /SaveMergeData, this option has the same effect as /SaveTextData.
§ Command line only option.
/SaveTextData[=<filename>.txt]
Saves the data to an ASCII text file (.txt) without displaying any PureCoverage windows. For example:
coverage /SaveTextData=myapp1.txt myapp.exe
If you do not specify a file name, PureCoverage uses <exename>.txt and saves the file in the same location as your program.
If an identically named file already exists, PureCoverage automatically 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 /SaveData command to generate both an ASCII text file and a PureCoverage data file. This is useful when you want a text file that a script can parse and a .cfy file to analyze using the PureCoverage user interface.
§ Command line only option.
/SelectiveInstrumentation=no|yes
Specifies whether you want to use selective instrumentation to instrument and collect coverage data only for modules you specify using the /SelectedModuleList option. For example:
coverage /SelectiveInstrumentation /SelectedModuleList=my_other.dll;myapp.dll myapp.exe
PureCoverage runs myapp.exe, but it collects data only for my_other.dll and myapp.dll.
By default, PureCoverage 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.
/SelectedModuleList=<module1[,T|P|N][,L|F];module2[,T|P|N][,L|F];...>
Specifies modules you want PureCoverage to instrument using selective instrumentation, and the instrumentation state and coverage level for each module. Separate multiple modules with semicolons.
When you use the /SelectedModuleList option, you must also specify the /SelectiveInstrumentation option. For example:
coverage /SelectiveInstrumentation /SelectedModuleList=my_other.dll,T,F;myapp.dll myapp.exe
PureCoverage runs myapp.exe, but it collects coverage 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. coverage level: 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.
/ShowInstrumentationProgress=no | yes
Specifies whether to display the Instrumenting dialog box, showing PureCoverage's progress as it instruments files. For example:
coverage /ShowInstrumentationProgress=no myapp.exe
By default, PureCoverage 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 PureCoverage instruments files required by calls to LoadLibrary. For example:
coverage /ShowLoadLibraryProgress=no myapp.exe
By default, PureCoverage 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:
coverage /SourcePath="D:\app\src;C:\thirdpartylibs\db\src" myapp.exe
By default, PureCoverage uses the following search order to locate source files:
1. The directory where the program you're monitoring is located.
2. The search path specified in the Files tab in the Settings for <exename> dialog box.
3. For Visual C++ programs, the directories specified in the Visual Studio Workspace file.
4. The search path specified in the Files tab in the Default Settings dialog box.
5. For Visual C++ programs, the MFC and Visual C++ directories.
6. The PATH environment variable.
7. Source path substitution specified in the Source Code tab of the Preferences dialog box.
Annotated source code is available only if debug line information is available and if a module was monitored at line level. Annotated source code showing line-by-line coverage data is not available when monitoring Visual Basic 6.0 p-code 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:
coverage /UndoReplace /UndoModuleList=myapp.exe
§ /UndoSelective: to change the instrumentation state of modules you instrumented using selective instrumentation, to the None state. For example:
coverage /UndoSelective /UndoModuleList=my_other.dll;myapp.dll
PureCoverage 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:
coverage /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:
coverage /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 PureCoverage installation.
§ Command line only option.
/?
Displays the syntax for command-line options.
§ Command line only option.
<filename>.cfy | <filename>.pcy
Displays a previously saved PureCoverage data file (.cfy) or Purify error and coverage data file (.pcy). For example:
coverage D:\purecoverage\testing\myapp.cfy
§ Command line only option.
Syntax Notes:
§ Any PureCoverage options you specify must precede the name of the program. PureCoverage interprets anything after the name of the program as an argument passed to the program.
§ You must place quotation marks around strings with embedded spaces. For example: /CacheDir="C:\Program Files\My Java 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, PureCoverage ignores the case and any hyphens or underscores in the option name. For example, the option /SaveTextData is equivalent to /Save_Text_Data, -SaveTextData, and /save-text-data.
(C) Copyright IBM Corporation 1993, 2010.