Rational Developer for System z

Invoking the code review application

This topic describes how to run the code review application from the Linux or Windows command line.
Note: Before you run the code review application:
  • Close any open Eclipse workspaces.
  • Allow any running instances of the code review application to run to completion.

Syntax for invoking the code review application

The code review application is invoked by entering a command on the Linux or Windows command line. There are parameters for setting the workspace, the source code location, the analysis scope, the analysis rule set, and the repository for output data files. You can enter the parameters in any sequence. Use environment variables if necessary to shorten the length of the command line. Be sure to:
  • Enter the command as a single line.
  • Use fully qualified paths for directories and files.
  • Put quotation marks around any parameter value that contains spaces.
The syntax is as follows:
Figure 1. Syntax for invoking the code review application

eclipse_directory\eclipse | eclipse.exe
     -application com.ibm.rsaz.analysis.commandline.AnalyzeApplication
     -data workspace_directory
     -rulefile rule_file
     [-projects P1[, P2, P3, ...] |
     -directory D1[, D2, D3, ...]]
     [-includefile include_file]
     [-excludefile exclude_file]
     -exportdirectory export_directory
     [-nosplash]
     [-verbose]
     [ >output_file
]

where:

eclipse_directory\eclipse | eclipse.exe is the fully qualified path of the Eclipse executable file. Use eclipse for Linux or eclipse.exe for Windows.
     -application com.ibm.rsaz.analysis.commandline.AnalyzeApplication is the name of the code analysis component.
     -data workspace_directory is the fully qualified path of the Eclipse workspace that you are using.
     -rulefile rule_file is the fully qualified path of a .dat file containing a set of rules and severities that you exported from the analysis configuration editor.
     -projects P1[, P2, P3, ...]  is a comma-separated list of projects in the workspace that contain source files.
     -directory D1[, D2, D3, ...] is a comma-separated list of directories that contain source files.
     -includefile include_file is a file containing a list of files to be included in the code review.
     -excludefile exclude_file is a file containing a list of files to be excluded from the code review.
     -exportdirectory export_directory is the fully qualified path of a directory where output data files are  written.
     -nosplash suppresses the display of the Eclipse splash screen.
     -verbose causes output information to be written to standard output.
     > output_file is a text file which captures output information written to standard output.

Note: The following Eclipse parameters are not supported:
  • -reportdirectory
  • -projectname
  • -bindirectory
  • -javacp

Parameters of the code review application

Table 1 describes the application parameters of the code review application:

Table 1. Code review application parameters
Header Type Description
-application Required com.ibm.rsaz.analysis.commandline.AnalyzeApplication

This parameter specifies the identifier of the Eclipse application to be invoked. Use the text string shown above, which identifies the code review application.

Type this text exactly as shown.

-data Required This parameter specifies the path of the Eclipse workspace that the code review application uses. It must be a fully qualified path.

If the specified workspace does not exist it is created.

If you also use the -projects parameter, the code review application searches in this workspace for the specified projects.

If you do not specify either the -projects parameter or the -directory parameter, the code review application analyzes all the projects in the specified workspace.

-rulefile Required This parameter specifies the fully qualified path of a rule file that contains a set of code review rules and their assigned severities. The code review application applies these rules to the projects or files specified in the invocation.

For COBOL the rules can include custom categories and rules and user-written custom rules.

Rules for COBOL, PL/I, and Java™ can be contained in the same rule file. During processing the code review application determines the programming language of each source code file that it finds and then applies to it the rules that are applicable to that language.

The rule file must have the extension .dat. It must be located in the file system of the workstation where the invoked eclipse.exe file is installed.  It cannot be accessed across a network nor across an intranet or internet.

You create the rule file by exporting selected rules from the analysis configuration editor using the Export button.

-projects
-directory

Optional These two parameters specify the locations of source code files to be analyzed. (You can also use the parameters -includefile and -excludefile to include or exclude specific files.)

Use -projects when the source code files are located in a project inside the workspace that you specify in the -data parameter.

Use -directory when the source code files are located in a directory outside the workspace that you specify in the -data parameter.

If neither -projects nor -directory is specified, the code review application analyzes the source code files in all of the projects in the specified workspace.

If -projects P1[, P2, P3 ...] is specified, the  application processes all the source code files in the comma-separated list of projects P1, P2, P3.....

If -directory D1[, D2, D3, ...] is specified, the application processes all the source code files in the comma-separated list of directories D1, D2, D3, ....

If both -projects and -directory are specified, the application processes the -projects parameter and ignores the -directory parameter.

Temporary projects created with the -directory parameter: The following discussion applies to directories located outside the workspace specified in the -data parameter.

Use of the -directory parameter has two side effects:
  • For each directory specified in the -directory parameter, a temporary project with the same name plus a prefix such as genericProject_ or analyzedAsJava_ is created in the workspace specified in the -data parameter. For example, if the directory c:\SourceFiles\CobolDirectory_0001 is specified in the -directory parameter, then a temporary project such as genericProject_CobolDirectory_0001 is created in the workspace. Each temporary project is an Eclipse linked resource that is linked to the corresponding original directory in the local file system.
    You can delete these temporary projects from the workspace.
    Note: However, take care to follow the recommended procedure for deleting a resource link, so that you do not delete the contents of the corresponding directory in the file system. See Deleting temporary projects created by the -directory parameter.
  • Directory paths in the CSV Analysis Results file and in the XML Analysis Result file include the names of the temporary projects.
    Note: You might need to modify these paths before using the result files as input to other applications.
CAUTION:
Do not use the -directory option to specify directories located inside the workspace that you specify in the -data parameter. Doing so creates temporary projects in the workspace that are Eclipse linked resources linked to the specified directories. Deleting a temporary project incorrectly can cause your original project, folders, or source code files to be deleted. See Deleting temporary projects created by the -directory parameter.

-includefile Optional This parameter is used only when the -directory parameter is present. It specifies the fully qualified path of a text file containing a list of source code files to be analyzed, one file per line.

When both the -directory parameter and the -includefile parameter are present, the code review application analyzes only those source code files that are specified in the include file and that occur in one of the directories  specified in the -directory parameter.

Each  entry in the include file must be either a file name or a relative path plus a file name.  The code review application searches for each entry in each of the specified directories.

-excludefile Optional This parameter is used only when the -directory parameter is present. It specifies the fully qualified path of a text file containing a list of source code files to be excluded from analysis, one file per line.

When both the -directory parameter and the -excludefile parameter are present, the code review application excludes from analysis  those source code files that are specified in the exclude file and that occur in one of the directories specified in the -directory parameter. All files that are not excluded are analyzed.

Each  entry in the exclude file must be either a file name or a relative path plus a file name.  The code review application searches for each entry in each of the specified directories and excludes the file if it is found.

-exportdirectory Required This parameter specifies the fully qualified path of the directory to which the code review application writes its XML and CSV output data files. These data files can be used as input to other applications.

All the supported types of output data files are generated.

If this parameter is omitted no output data files are generated. However, the application  still writes output information to standard output, if that option is specified.

-nosplash Optional This parameter suppresses the display of the Eclipse splash screen.

-verbose Optional This parameter causes the code review application to write output information to standard output.
Note: On the Windows operating system, to capture output information you must not only specify the -verbose parameter but also redirect standard output to a file on the command line:
-verbose >output_file
>output_file Optional Use this redirection on the command line to capture the application output information in a file.

On Windows you must also specify the -verbose  parameter to get output information.

Including copy books or include files

Most referenced copy books and include files are processed, but each must meet the following two requirements:
  • A main source code file refers to the copy book or include file, and this main source code file is not excluded from processing; and
  • Either of the following situations is true:
    • The copy book or include file is present in the same project or directory as the main source code file.
    • A local property group is associated with the project containing the main source code file, and the SYSLIB field in the Local Compiler Options group contains the path of the project containing the copy book or include file.
      Note: To check the value in the SYSLIB field:
      1. Open the Property Group Manager view.
      2. Expand LOCAL and double-click a local property group.
      3. In the Property Group Information tab, click the COBOL or PL/I tab.
      4. In the left pane, click Local Compiler Options.
      5. In the right pane, check the value in the SYSLIB field.

Sample invocations

These sample invocations illustrate how to invoke the code review application. Enter the invocation as one line on the Linux or Windows command line:

  • Using the -project parameter with two COBOL projects:
    C:\progra~1\IBM\SDP\eclipse.exe 
    -application com.ibm.rsaz.analysis.commandline.AnalyzeApplication 
    -data "C:\RDz 85 workspaces\workspace_851_0914" 
    -rulefile "C:\RDz 8.5\CodeQuality\results\cobolRules.dat" 
    -projects "My COBOL project 0001","My COBOL project 0002" 
    -exportdirectory "C:\RDz 8.5\CodeQuality\CommandlineResults\Results851" 
    -nosplash 
    -verbose > c:\commandlineResults\out851_0916_COBOLProjects.txt
  • Using the -directory parameter and the -excludefile parameter:
    C:\progra~1\IBM\SDP\eclipse.exe 
    -application com.ibm.rsaz.analysis.commandline.AnalyzeApplication 
    -data "C:\RDz 85 workspaces\workspace_851_0914" 
    -rulefile "C:\RDz 8.5\CodeQuality\results\PL1Rules.dat" 
    -directory "C:\CheckSourceCode\PL1_Files_0001" 
    -excludefile "C:\RDz 8.5\CodeQuality\directoryExcludeFiles.txt"
    -exportdirectory "C:\RDz 8.5\CodeQuality\CommandlineResults\Results851" 
    -nosplash 
    -verbose > c:\commandlineResults\out851_0916_PL1Projects.txt

Using the output data files

The output data files are written to the export directory specified in the command line when the code review application is invoked. The application creates a new subdirectory for output files each time the application is invoked. The name of the subdirectory consists of the date plus the time in the format YYYYMMDD_hhmmss where YYYY is the year, MM is the month, DD is the day, hh is the hour, mm is the minutes, and ss is the seconds. For example,
20121008_101746
The number of output data files that are created depends on the number of exporters that are registered with Eclipse. The code review application creates a separate data file for the output data from each registered exporter.
Note: In the analysis configuration editor you can export code review results to these same types of data files.
If you are analyzing COBOL or PL/I source code files, typically there are five output data files generated. The most comprehensive sets of data are in the first two files listed:
XML Analysis Results.xml
Contains all the result information in XML format. The XML schema of this format is shown in View the schema of the XML format. This type of file is a data source for Rational® reporting tools and similar products.
CSV Analysis Results.csv
Contains all the result information in CSV format. The fields and values for this format are shown in View the fields of the CSV format. This type of file is easily imported into spreadsheet software and can be a data source for comparison tools.
Executed Rules.xml
Contains a list of the rules that were applied in the code review, ordered by provider. Each rule entry contains the text of the rule and its assigned severity.
Scanned Resources.xml
Contains a list of the source code files that were analyzed in the review.
XML Analysis Results.xml
Contains a high-level summary of the code review process.
Note: If the scope include Java source code files then additional output data files are generated.

Using the output information

The output information is the information that the code review application writes to standard output. It includes a report link, a list of results, and a result count.

The report link is a URL to a server where output data files could potentially be copied. This link has no significance in Developer for System z®, and you should therefore ignore it. An example:
[url]http://server:9090/rsar/reports/20121004_162226/[/url]

The list of results lists each rule one at a time, followed by a list of the source code files and line numbers where the rule was applied.

The result count states the total number of times that a rule was applied, for all the listed rules.

Deleting temporary projects created by the -directory parameter

When you delete a temporary project that was created as a link to a directory specified in the -directory parameter, take care to follow the recommended procedure for deleting an Eclipse resource link, so that you do not delete any of the contents of the corresponding directory in the file system.

To delete a temporary project:
  1. Start Developer for System z with the same workspace that you specified in the -data parameter when you invoked the code review application.
  2. In the Navigator view, do the following:
    1. Right-click the temporary project name and click Delete.
    2. When prompted to delete the project contents on disk, click OK.
Note: Deleting a linked resource does not cause the corresponding resource in the file system to be deleted. However, deleting child resources of a linked folder does cause them to be removed from the file system. See the following topics on linked resources:

Preferences


Feedback