Set up a Jazz Build Engine to run an Ant script: Part 1. Setup build definitions

Learn how to set up an IBM Rational Team Concert main build that performs an IBM Rational Developer for System z code review. Based on the result of the code review, the process either submits the build to compile, or stops and reports the code review errors. Apply the tested, documented sample described in this article to implement a similar solution on your own platform. The steps focus on the Rational Team Concert administrator who writes an Ant task to compile COBOL programs, depending on other previous tasks, such as quality control. Part 1 describes the technical and functional context of the scenario, and the Jazz Build Engine configuration.

Corinne Blanchard (blanchard_c@fr.ibm.com), Rational client technical professional, IBM

Author1 photoCorinne Blanchard has 20 years of experience in the application development field (Cobol, Pacbase, J2EE). In the last six years she has worked for IBM on Rational products as a client technical professional and team leader for Rational Enterprise Modernization tools. In 2010, she contributed to the IBM Redbooks IBM WebSphere RFID handbook: A solution guide and IBM WebSphere RFID handbook: A programming guide. In 2013, she wrote a workbook that explains the basics of IBM Rational Programming Patterns.



18 March 2014

Overview

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
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
FolderFileComments
IBM_POT Main folder
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

Click to see code listing

Listing 1. Contents of the jbe-win.bat file

cd C:\RTC-BuildSystem-Toolkit-Win_4.0.3.0-RTC-I20130517-1856\jazz\buildsystem\buildengine\eclipse

jbe -vm "C:/Program Files/IBM/JazzTeamServer_403/server/jre/bin/java" -repository https://clmweb:9443/ccm/ -userId cblanchard -pass cblanchard -engineId bvap.jbe.engine.dev.win

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
Jazz Build Engine runs build loop and waits

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
image003.jpg

Click to see larger image

Figure 3. Build engine bvap.jbe.engine.dev.win

image003.jpg

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
Build definition in 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
Build definition in JazzSourceControl tab

Click to see larger image

Figure 5. Build definition: JazzSourceControl tab

Build definition in 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
Build definition file and toolkit in Ant tab

Click to see larger image

Figure 6. Build definition: Ant tab

Build definition file and toolkit in 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.


Acknowledgements

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.


Download

DescriptionNameSize
Code sampleCodeReview.zip32

Resources

Learn

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.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=965551
ArticleTitle=Set up a Jazz Build Engine to run an Ant script: Part 1. Setup build definitions
publish-date=03182014