This series of articles explains how to use IBM® Rational Team Concert™ to perform a code review. Based on the result of the code review, the process either submits the real build to compile, or stops and reports the code review errors.
The process is based on two build definitions:
- A definition that targets the z/OS® platform, which is in charge of compiling mainframe programs.
- A build definition that runs on the Microsoft® Windows®
platform and orchestrates the following tasks:
- Performs the code review
- Submits the z/OS build, depending on the results of the code review
- Reports errors
The code review is done using the IBM® Rational® Software Analyzer engine, which is integrated in:
- IBM® Rational® Application Developer for C++ and Java® rules,
- IBM® Rational® Developer for System z® for COBOL rules,
- IBM® Rational® Programming Patterns for Pacbase rules.
The sample described in this article addresses a quality control process that uses COBOL rules defined within IBM Rational Developer for System z.
This article does not include how to set up an IBM Rational Team Concert dependency build running on z/OS to compile mainframe programs. Assume the z/OS build is already in place and is working fine.
This article describes how to set up the main build that orchestrates the code review and the mainframe build. This build is supported by a build definition based on the Jazz™ Build Engine. It runs on Windows.
The build is defined through an Ant-based script that performs various steps, which are described in detail.
Although this article relies on an example with COBOL sources, you can apply the same steps to other contexts, such as C++ or the Java programming language. The quality control engine natively offers rules for each of these programming languages. In a Java context, for example, some steps dedicated to mainframe applications can be skipped.
Functional context for the sample scenario
After a successful development phase, the code is to be promoted to a qualification environment. Before it can be delivered to the qualification environment, it must undergo a code review.
This scenario addresses a team build. You can implement a personal build using similar steps, but that requires significantly more time.
Assume that each time the code is promoted, it is checked for quality. Therefore, the current code review is to focus on the programs that have been changed since the last promotion. This scenario uses a dependency build.
This sample scenario measures integrity for the complete application. Any failure to respect the code review rules prohibits the promotion. In this step, if a severe error is detected by the code review, the compile build is not submitted.
Within the rules to be checked by the code review, some rules pertain to the Rational Programming Patterns design (VisualAge Pacbase model). To address these rules, the Rational Software Analyzer engine needs to use internal Rational Programming Patterns indexes. These indexes are not necessarily up to date and need to be refreshed by using a RPP synchronize task. Currently, IBM Rational Programming Patterns command lines are available for the Windows platform only. For this reason, in this scenario, the Jazz Build Engine is located in the Windows environment.
Technical context for the sample scenario
As shown in Figure 1, the sample scenario is implemented on a laptop that runs Windows 7. Two distinct VMware images are used:
- A VMware based on Linux®:
- Rational Development and Test Environment for System z is installed and provides a mainframe environment to compile COBOL programs.
- A Rational Team Concert server is installed on the Linux platform
- A z/OS build engine and a build definition supported by the build engine is defined in Rational Team Concert.
- A VMware based on Windows 7:
- Eclipse clients are installed for Rational Developer for System z, Rational Team Concert Enterprise Edition, Rational Programming Patterns.
- Jazz Build Engine is installed on Windows platform.
- A Windows build engine and build definition supported by the build engine is defined in Rational Team Concert.
Figure 1. Technical context for the sample scenario
The following software is used:
- Rational Team Concert Enterprise Edition v4.0.3
- Rational Developer for System z v9.0
- Rational Programming Patterns v9.0
Additional information available with this article
You can download a zip file that contains all the files that are used or generated. Table 1 shows the structure of the files. Names for files that are generated appear in bold font.
Table 1. Structure of the downloadable zip file
|BVAP-CQ||Target for local download of the build workspace|
|BUILD_PARAMETERS||IBM Rational Team Concert component where build parameters are stored|
|build.xml||Ant script related to master build|
|CodeReview||CodeReviewCde.bat||Code review command line|
|CodeReview||exportUserRules.dat||Code review rules exported|
|CodeReview||transform_html.xsl||XSL Transformation from csv to html file|
|PreviewBuild||buildPreview.properties||Build properties overridden|
|PreviewBuild||transform_txt.xsl||XSL Transformation from xml to txt file|
|RppSync||synch.bat||IBM Rational Programming Patterns Synchronize command line|
|Results||Folder with temporary and/or generated files|
|CodeReview||report.html||Code review results using html format|
|CodeReview||TraceCQ.log||Code review log parsed by Ant script|
|TIMESTAMP||Results generated by IBM Rational Software Analyzer|
|PreviewBuild||buildableFiles.txt||Preview build results using txt format|
|PreviewBuild||buildableFiles.xml||Results generated by Preview Build|
|RppSync||TraceRppSync.log||Synchronize log parsed by Ant script|
Ant tasks implement build engines
A first build engine runs on z/OS. This build engine supports a build definition declared as a Rational Team Concert dependency build, which is used to compile COBOL artifacts. Assume this z/OS build is already in place and is working. Think of this build as the subordinate build, because it is launched on demand by the main Ant script.
A second build engine runs on Windows. This build engine supports a build
definition created with template
Ant – Jazz Build Engine.
Think of this build as the master build, because it drives the
different tasks to be submitted and it requests builds.
The following steps are required for the master build:
- The Jazz Build Engine configuration
- The Ant script, which sequences the steps:
- The preview build, to indentify the buildable files
- The COBOL code review, which is limited to the buildable files
- The dependency build, to compile COBOL source on z/OS
Jazz Build Engine configuration
Because the master build is supported by Jazz Build Engine, you need to download and install a Jazz Build Engine for the Windows environment. Use the command, shown in Listing 1, to start this process. You can also find this command in the jbe-win.bat file in the downloadable zip file.
Listing 1. Contents of the jbe-win.bat file
After the Jazz Build Engine is started, it waits for a request, as shown in Figure 2.
Figure 2. Jazz Build Engine waits for a request
Build engine for the Windows Jazz Build Engine
To learn how a build engine is created, see the Jazz.net article Getting started with Ant Builds on the Jazz Build Engine. In this article, the build engine is named bvap.jbe.engine.dev.win, as shown in Figure 3.
Figure 3. Build engine bvap.jbe.engine.dev.win
Build definition for Windows Jazz Build Engine
To learn how a build definition is created, see the Jazz.net article Getting started with Ant Builds on the Jazz Build Engine. In this article, the build definition is named bvap.dev.TeamBuild_CodeReviewAndBuild, as show in Figure 4. This build definition is supported by the previously created build engine.
Figure 4. Build definition: Overview tab
This build definition is defined for a Build Workspace, as show in Figure 5. In this example, the Build Workspace is used only to submit the build for code review (but it is possible to reuse the same Build Workspace when you submit a build for compile).
Figure 5. Build definition: JazzSourceControl tab
It is important to know that when a build is to be requested, the Jazz Build Engine loads locally, in a sandbox, the contents of the build repository workspace, after it accepts the differences from the previous version. For this sample scenario, the sandbox is stored in folder C:/IBM_POT/BVAP-CQ.
This build definition runs the specific Ant script for this scenario, as shown in Figure 6.
Figure 6. Build definition: Ant tab
The field Build file is filled with the path of the Ant script, which is described in the next step.
Export rules for code review
In this example, code review is launched using the command line.
When you run the code review application command, you have to specify parameters, such as the path of the rules file to check. Therefore, it is necessary to export the code review rules in a .dat file.
For this example, the rules file contains different Rational Programming Patterns rules, including a user-written rule. You can see the contents of the rules file, exportUserRules.dat, in Listing 2. The file exportUserRules.dat is included in the downloadable zip file included with this article.
Listing 2. Contents of exportUserRules.dat file
rpp.codereview.cobol.rules.DfhRespRule rpp.codereview.cobol.rules.DfhRespRule.variable.SEVERITY,1 ... pluginprojectforcobolcodereview90.CobolRule pluginprojectforcobolcodereview90.CobolRule.variable.SEVERITY,2 ... com.ibm.pdp.qualitycontrol.cobol.rules.RppCicsLinkStatementRule com.ibm.pdp.qualitycontrol.cobol.rules.RppCicsLinkStatementRule.variable.SEVERITY,1
For more information about how to export rules into a .dat file, consult the Rational Software Developer for System z information center.
Part 2 of this series describes how to use an Ant-based script, build.xml, which runs on the Jazz Build Engine, to define the master build.
The author expresses gratitude to Nicolas Dangeville, Benoit Jaunin, and Tony Chen Zhang Hong for implementing this functionality and to Jean-Yves Baudy, Christian Chalumeau, Hervé Le Bars, Stéphane Leroy, Samira Bataouche, and Vincent Trébuchon for reviewing this article.
- More about Rational Team Concert:
- Find Rational Team Concert articles and links to many other resources on IBM developerWorks, and check the product overview page, features and benefits, system requirements, and the user information center.
- Check the Rational Team Concert page on Jazz.net.
- Watch the Using Rational Team Concert in a globally distributed team webcast or a demonstration of the Dashboards and reports, or listen to the podcast about IBM Rational Team Concert and Jazz.
- More about Rational Development and Test Environment for System z:
- More about Rational Programming Patterns from the product overview page.
- Explore the Rational software area on developerWorks for technical resources, best practices, and information about Rational collaborative and integrated solutions for software and systems delivery.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, anytime, and many of the Getting Started ones are free.
Get products and technologies
- Download Rational Team Concert from Jazz.net and try it free on up to 10 developers for as long as you want (requires registration). If you'd prefer, you can try it in the sandbox instead, without installing it on your own system.
- Download a free trial version of Rational Programming Patterns.
- Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.
- Get connected with your peers and keep up on the latest information in the Rational community.
- Rate or review Rational software. It's quick and easy.
- Share your knowledge and help others who use Rational software by writing a developerWorks article. Find out what makes a good developerWorks article and how to proceed.
- Follow Rational software on Facebook, Twitter (@ibmrational), and YouTube, and add your comments and requests.
- Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.