Help contents

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.

Macro basics

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

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"

Macro syntax

Macros are case insensitive. Put one command per line.

File names in macro commands must be enclosed in double 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.

An 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:

• Report type html, csv, txt: If the file exists, new reports will be added at the end.
• Report type rtf and pdf: If the file exists, the macro will fail. These reports are not possible to append to an existing file.
  The file existence check is done when loading the macro. If a file with the same name should be generated between the load and the execution of the command, the file may be overwritten without warning. This could happen if you execute the same macro with 2 instances of Project Analyzer simultaneously.

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.

Module members report

Report Members subtype [params]

The subtype parameter must be one of the following:

The optional params parameter can be one of the following:

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.

• ProjectPrinter creates a source code web site with reports.
• CommentManual creates a comment manual using specially formatted comments.
• CommentManualUnformatted creates a comment manual with unformatted comments.

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

• With HTMLSite, the "directory" parameter is required. It must be a valid directory name, existing or not. Quotation marks are required. All existing files in the directory are subject to being overwritten by new ones, so use this command with care. Notice that there is no IN keyword for the HTMLSite directory, as opposed to MHT.
• With MHT, the "filename.mht" parameter is optional. If given, Project Analyzer will save the report in that file. Use the DELETEOLD keyword to overwrite any existing file. You can also specify a directory name by preceding it with the IN keyword. Project Analyzer will create a new .mht file in that directory. The IN keyword is required with MHT if the target is a directory. If there is no directory or file name, Project Analyzer will create a new MHT file in the same directory as the macro file.
• A preceding SetReport command does not affect these macros.
• A following OpenReport command can be used to view the generated file(s) in the web browser.

Switches

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

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.

For ProjectPrinter, the default options are:

ProjectPrinter ... REPORTS CALLS CALLEDBY NOPROBLEMS LINENUMS

To override the defaults:

ProjectPrinter ... [NOREPORTS] [NOCALLS] [NOCALLEDBY] [PROBLEMS] [NOLINENUMS]

For CommentManual and CommentManualUnformatted, the defaults are:

CommentManual ... REPORTS ALL

To override the defaults:

CommentManual ... [NOREPORTS] [NONPRIV|EXP]

ProbFilter

ProbFilter filtername

Select a problem filter by name. If using a built-in filter, include the name in < > as in <Style>. If using a custom problem 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:

• autocomment: The comment prefix for auto-fixed problems is '! for VB Classic projects and 'HACK: for .NET projects. Dead code will be commented out with '+ .
• manualcomment: The comment prefix for manual fix problems is '! for VB Classic projects and 'TODO: for .NET projects.
• manualalert: The prefix for manual fix problems is $.

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

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

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:

You could use the parameters like this:

' Analyze a project in the working directory
Analyze "%0\%1"

' Produce 2 reports in summary.txt in the working dir
SetReport txt "%0\summary.txt" DELETEOLD
Report Summary
Report Quality

' Produce another report in c:\scripts
' (path relative to 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.

See also

©Aivosto Oy Project Analyzer Help