Project Analyzer Macros

Enterprise Edition only

Project Analyzer Enterprise Edition supports .pam macro files. Write your own macros to automate repetitive code analysis tasks: analyze several projects in one run and generate several standard reports at once.

The macros run unattended. You can use macros to run analyses in the background. You can leave a macro running while you sleep or drink coffee. You can even execute macros from a batch file (.bat). During macro execution, the Project Analyzer window is displayed normally but it doesn't take or require any user input.

How to write a macro

.pam files are standard plaintext files. Use your favorite text editor like Windows Notepad to create them. Sample macros

How to run a macro

There are two ways to run a macro.

  1. Select the Run macro command in the Enterprise menu.
  2. Run a .pam file from the command line with this syntax: project.exe "macro.pam"

Syntax conventions

File names in macro commands must be enclosed in quotation marks. Any relative file or path names are relative to the location of the .pam file. If you omit the path from a file name, the file is assumed to be in the same directory as the executed .pam macro.

Macros are case insensitive. One command per line.

Apostrophe ( ' ) at the start of a line marks a comment. Only full-line comments are supported. A comment line must not include any commands.

Available commands

Analyze, SetReport, Report, OpenReport, FindDuplicateCode, ProjectPrinter, CommentManual, CommentManualUnformatted, ProbFilter, AutoFix, SaveMTX, SaveMTXxml, OpenMTX, SaveSUD, Log, Include, Quit.

Parameter substitution

Analyze

Analyze "projfile" [configname] [BIN] [DLL]

Analyze a VB project, project group or solution. Projfile is the name of the .vbp, .vbg, .vbproj, .sln or .mak file. The entire code is analyzed.

If you want to accomplish a partial project analysis of selected files only, generate an artificial project. Copy your project file as a new file, open it in VB and remove those files you don't want in the analysis.

You may include several Analyze commands in one macro file to analyze several projects sequentially. The Analyze command clears any results from the previous analysis.

The optional parameter configname allows you to select a VB.NET project configuration. The standard confignames are Debug and Release. If you don't specify a configname, no configuration settings will be in effect. The configuration settings include information about project-level compiler constants, such as DEBUG and TRACE. If you don't use project-level compiler constants, you can ignore this parameter. This parameter is case sensitive.

The optional parameter BIN enables COM analysis and .NET assembly analysis for all binary files referenced in the project(s). If you omit it, no binaries are analyzed. (The parameter BIN is equal to the now obsolete parameter named COM.)

The optional parameter DLL enables DLL analysis. If you omit it, DLL analysis is not performed.

SetReport

SetReport html "file.html" [DELETEOLD]
SetReport csv "file.csv" [DELETEOLD]
SetReport txt "file.txt" [DELETEOLD]

SetReport rtf "file.rtf" [DELETEOLD]
SetReport pdf "file.pdf" [DELETEOLD]

Selects the format and file to save reports in. This command affects all the successive reports generated by commands Report and FindDuplicateCode. As with all macro commands, the file path is relative to the location of the main macro file. If you don't enter a path, the report file will appear in the same directory as the macro.

Recommended use: Issue SetReport immediately before each Report or FindDuplicateCode command. This way each of your reports will go to a new file.

It's also possible to use a single SetReport with several Report/FindDuplicateCode commands. This will put several reports into one file. It works with html, csv or txt file types, but not with rtf or pdf.

Parameter DELETEOLD

If you add the optional DELETEOLD parameter, any existing file with the same name will be deleted.

If you omit DELETEOLD and the file exists already, this is what will happen:

Alternative syntax: Automatic report filename

SetReport type IN "directory"
SetReport type

This syntax allows you to let Project Analyzer pick a report filename automatically. Replace the word type with the report file type (html, rtf, pdf, csv, txt) as above.

By specifying the IN "directory" parameter, the report file will appear in this directory. By omitting this parameter altogether, the report file will appear in the same directory as the main macro file. The automatically generated report filenames are of the form rpt001.txt etc.

Report

Report reportname

Generates a report to the file specified by the previous SetReport command. The reportname parameter is required; it is not enclosed in quotation marks.

ReportnameReport created
Lists
FilesFile list
FilesDetailedFile list with details
FilesBySizeDateFile list by size and date
FilesProjectsFiles and projects
ModulesModule list
NamespacesNamespace list
ProceduresProcedure list
ProceduresAlphaProcedure list, alphabetical
ProceduresDetailedProcedure list with details
VariablesVariable list
ConstantsConstant list
TypesEnumsAliasesTypes, Enums and Aliases list (actual report may contain only some of these)
DictionaryDictionary
Reference reports
FileDepTreeFile dependency tree report
ProcCallTreeProcedure call tree (all procedures). This report may be excessively long on large projects, taking a long time to create or even causing a hang.
XrefCross-reference report
XrefPProcedure references report
XrefVVariable references report
XrefCConstant references report
FDAFile dependency analysis
FileDepLevelsFile dependency levels
SubsystemsSubsystems report
NonCohesiveNon-cohesive classes
VariableUseVariable use report
Modules and interfaces
ModuleInterfaces [subtype]Module interface report. The optional subtype parameter is one of:
  • ALL - All scopes
  • FRIENDPUBLIC - Friend and Public (this is the default)
  • EXP - Public exposed only
Members subtype [params]Module members report, see syntax below
InterfaceReportInterface report
User interface
FormsForm report
MenusMenu report
ControlsControl report
HotkeysHotkey conflicts report
Libraries and string literals
DLLsLibrary report
LiteralsString literal analysis
LiteralListString literal list
Problem reports
ProblemsProblem report sorted by location. The problems are selected according to currently selected problem filter (see command ProbFilter).
ProblemsByDescProblem report sorted by problem description. The problems are selected according to currently selected problem filter (see command ProbFilter).
ProblemStatsProblem statistics according to currently selected problem filter (see command ProbFilter).
DeadProcsDead procedures report
DeadStatsDead code statistics
Summaries
QualityDesign quality report
SummaryProject summary
Metrics and compatibility
CompatibilityVB.NET compatibility report
ProcMetricsProcedure metrics report
FileMetricsFile metrics report

Module members report

Report Members subtype [params]

The subtype parameter must be one of the following:

subtype Report created
ALL All procedures and variables
DATAINPUT Data input
DATAOUTPUT Data output
EXT External access
EXTDATAINPUT External data input
EXTDATAOUTPUT External data output
MODULEDATA Module data
PRIVATEDATA Private data
DATAREAD Data read access
DATAWRITE Data write access
PROPERTIES Properties
PROCEDURES Procedures
METHODS Methods
EVENTS Events
CTORS Constructors
CTORSFINALIZERS Constructors and finalizers
OUTPARAMS Procedures with out parameters
params Parameter style selected
NOPARAMS No parameters
PARAMTYPES Parameter types (this is the default setting)
PARAMNAMES Parameter names

OpenReport

Open the report file specified by the previous one of the following commands: SetReport, ProjectPrinter, CommentManual or CommentManualUnformatted.

OpenReport launches an external editor or viewer program. The launch options can be configured in the dialog box that shows up by selecting Options|Report to|File. If no setting is specified there, the default program for the file extension will be used as configured in the Windows System Registry.

FindDuplicateCode

FindDuplicateCode minlines [IGNORECOMMENTS] [IGNORELINENUMS]

Runs the Find duplicate code feature and generate a report. Requires a previous call to SetReport to specify the report file.

The parameter minlines is required. It is the minimum number of lines that are required to match before a code block is considered duplicated. The acceptable range for the minlines parameter is 4 to 10000.

The optional parameters IGNORECOMMENTS causes the detection to ignore comments. The optional parameter IGNORELINENUMS causes the detection to ignore line numbers and labels.

ProjectPrinter, CommentManual, CommentManualUnformatted

ProjectPrinter HTMLSite "directory"           [switches]
ProjectPrinter MHT "filename.mht" [DELETEOLD] [switches]
ProjectPrinter MHT IN "directory"             [switches]
ProjectPrinter MHT                            [switches]

In place of ProjectPrinter, you can also use commands CommentManual or CommentManualUnformatted with the above syntax.

These 3 commands run Project Printer to create a web site of your system.

You can have the web site created either as separate files (the HTMLSite option) or in a single MHT file (the MHT option):

Switches

You can optionally add switches to control the way the source web site or Comment Manual is created:

Switch Setting in Project Printer Default value
[NO]REPORTS Create reports REPORTS
ProjectPrinter specific switches:
[NO]CALLEDBY Called by CALLEDBY
[NO]CALLS Calls CALLS
[NO]PROBLEMS Show problems in code NOPROBLEMS
[NO]LINENUMS Line numbers LINENUMS
CommentManual and CommentManualUnformatted specific switches:
ALL
NONPRIV
EXP
All members: Private to Public
Non-private members only
Cross-project exposed members only
ALL

To disable a feature, prefix the switch with NO. To enable a feature, leave the NO prefix out. For example, REPORTS includes reports and NOREPORTS disables them. If you omit a switch, the default value will be in effect.

Thus, for ProjectPrinter you have the following defaults and options to override the defaults:

Defaults: ProjectPrinter ...  REPORTS     CALLS     CALLEDBY     NOPROBLEMS LINENUMS
Optional: ProjectPrinter ...  [NOREPORTS] [NOCALLS] [NOCALLEDBY] [PROBLEMS] [NOLINENUMS]

Similarly, for CommentManual and CommentManualUnformatted, you have the following defaults and options:

Defaults: CommentManual ...   REPORTS     ALL
Optional: CommentManual ...   [NOREPORTS] [NONPRIV|EXP]

ProbFilter

ProbFilter filtername

Select a problem filter by name. If using a built-in filter, include the name in < >. If using a custom filter, do not use < >.

AutoFix

AutoFix "dirname" [ autocomment | automanual | autoquiet ]   [ manualcomment | manualignore | manualalert ]

Use the Auto-fix function to generate a new, purified project. Uses the selected problem filter (current user selection or specified by the previous call to ProbFilter). This treats the whole project, that is, all VB source files. The auto* and manual* options correspond to the options described in Auto-fix options. Dirname is the directory in which the purified project will be generated. This directory must exist and be empty.

For your safety, Project Analyzer will not delete the files in it but will display an error message at macro load time. This command doesn't have the option to open the generated project in Visual Basic either.

The prefixes to use for adding comments to the code are pre-defined according to the following options:

SaveMTX, SaveMTXxml

SaveMTX "filename.mtx" [DELETEOLD]
SaveMTX IN "directory"
SaveMTX

SaveMTXxml "filename.xml" [DELETEOLD]
SaveMTXxml IN "directory"
SaveMTXxml

Save the analyzed metrics in a .mtx or .xml file. The SaveMTX command saves a regular .mtx metrics database, which you can open with Project Metrics Viewer. The SaveMTXxml command saves an XML export file.

  1. The first syntax saves the metrics in the given filename. Use the optional parameter DELETEOLD to overwrite an existing file when necessary. If you omit DELETEOLD, the macro fails if the file exists already.
  2. The IN "directory" syntax saves the metrics in the given directory. A new file is created automatically.
  3. If you omit the parameters, the file will be created in the default Project Metrics save directory. This is the same directory as given by the Configure menu command within the Enterprise menu of Project Analyzer. If the directory is not configured, the macro will stop to ask for the directory to save in.

OpenMTX

Open Project Metrics Viewer (mtxview.exe) to view .mtx metrics databases. Use this command to view metrics saved by SaveMTX. Does not work with SaveMTXxml.

If you issue OpenMTX after SaveMTX (but before the next Analyze command), the viewer will position the cursor on the last saved .mtx database if that database is on the search path.

SaveSUD

SaveSUD "file.sud" [EXPOSEDLIVE|EXPOSEDDEAD]

Save analysis results to a .sud file for Super Project Analyzer.

The EXPOSEDLIVE or EXPOSEDDEAD parameter is optional. It is used with projects that have a public (exposed) interface that other projects can call. EXPOSEDLIVE assumes that all exposed code is live regardless of whether it is found to be used or not. EXPOSEDDEAD allows exposed code to be marked dead according to normal dead code rules. You can use this parameter to skip the question that may pop up at SaveSUD when you execute the macro. If you get no question, you can safely omit the parameter.

Log

Log "file.log"
Log

Log the execution of the macro. Put Log as the first command to log all actions taken by the macro. If the log file exists, Project Analyzer will append lines to the end.

You can issue several Log commands to change the log file in the middle of the macro. If you omit the log filename, Project Analyzer will use the file "macro.log" in your Project Analyzer directory as the default log.

Project Analyzer requires exclusive write access to the log file. If it can't do this, it will still execute the macro but it won't generate the log. For this reason, if you have several Project Analyzer instances running macros at the same time, you should use different log files for them.

The log file will list all executed commands and success/failure information. Please notice that success doesn't necessarily mean the command was fully executed as entered. For example, a report may have been redirected to the display if the macro couldn't open the report file for writing. In this case, the report was successful even if it wasn't created in the requested file.

Include

Include "file.pam"

Include a macro file in another. Use this to create a parent macro that "calls" a child macro. Notice that inclusions cannot be recursive, i.e. a macro cannot Include itself either directly or indirectly.

Quit

Exit Project Analyzer and end execution of macro. If not present, Project Analyzer will keep running when the macro execution ends.

Parameter substitution

If you run the macro from the command line, you can use up to 9 parameters: %1, %2, ..., %9. Each command line parameter that follows the macro filename will become one parameter for the macro.

Although not strictly required, it's advisable to enclose all parameters on the command line in quotation marks. Project Analyzer will use them for parsing the parameters correctly and remove them when done.

Special parameter %0

When run from the command line, the parameter %0 contains the working directory. You can use it to run the same macro file from different directories. By default, all file names are relative to the location of the macro file. You can use %0 to work relative to the directory you call the macro from.

Parameter example

Suppose you run the following command line from directory c:\source.

project.exe "c:\scripts\macro.pam" "myproject.vbp"

The parameters will contain the following values:

ParameterValueDescription
%0c:\sourceWorking directory
%1myproject.vbpParameter 1 (without quotation marks)

You could use the parameters like this:

' Analyze a project in the working directory
Analyze "%0\%1"
' Produce 2 reports in a file in the working directory
SetReport txt "%0\summary.txt" DELETEOLD
Report Summary
Report Quality
' Produce another report in c:\scripts (the path is relative to the location of macro.pam)
SetReport txt "files.txt" DELETEOLD
Report Files

Note the use of the quotation marks.

Use of parameters

You can use parameter substitution to run the same macro on several projects. For example, you can write a batch file to run the macro with different parameter values. The use of parameter substition is not restricted to file names, you can use them anywhere in the macro file.

The value of a parameter not given on the command line is an empty string. For example, if you give 2 parameters, the parameters %3 .. %9 will contain an empty string.

The syntax %0, %1, ..., %9 is not available for macros run from Project Analyzer's Enterprise menu. You need to run such a macro from the command line.

Unsupported macros

The following obsolete macro commands have been removed or replaced.

MacroReplacement
Report CallDepthFeature removed, no replacement
Report ModuleDiagramsReport Members All
Report InterfacesReport ModuleInterfaces

See also

Sample macros

©Aivosto Oy - Project Analyzer Help Contents