Building IBM i Application using the IBM i Dependency Build Template.

Building IBM i Application Using IBM i Dependency Build

Created By: Iftikhar Ahmed Sheikh

Contents

Building IBM i Applications Using IBM i Dependency Build Template. 1

About this task. 1

Procedure. 1

Building IBM i applications using the new IBM i Dependency Build Template ?

Building IBM i applications using the new IBM i Dependency Build Template

o??Overview

o??Prerequisites

o??Configuration and setup

o??Introduction to IBM i dependency build artifacts and concepts

o??Performing builds and examining results.

o??Incremental builds

o??Working with Source Code Data

o??Summary

Overview

This document demonstrates the use of the new IBM i dependency build template to build IBM i projects.?The IBM i dependency build template was introduced in version 4.0 of Rational Team Concert (RTC); it provides users with a new way to build IBM i applications incrementally.??

Prerequisites

• The following client products have been downloaded and installed:
• Rational Team Concert (RTC)
• Rational Developer for ?i (RDi) with the integration feature selected.??
• RDi is not required to perform builds, but its use in IBM i application development is highly recommended.?Some RDi functionality is described in this article.
• Access to a Rational Team Concert server running at the equivalent version.?The server can be running on any supported platform.
• An equivalent version Build Server Toolkit running on your IBM i build server.?Take note of the Jazz user specified here, as it is used to connect to the RTC server during the build.?This user should belong to the "JazzAdmin" group and should have a?Rational Team Concert - Developer for IBM Enterprise Platforms?license.?The userTestJazzAdmin1?was used to develop this article.
• Working knowledge of Eclipse based IDE’s.?Helpful but not required would be a background in IBM i development, and basic user knowledge of Rational Developer for Power and Rational Team Concert products.

Configuration and setup

This section lists the configuration and setup required to build the Maillist application with the new IBM i dependency build template.

1. Create a build engine of type?Rational Build Agent?connecting to a Build Server Toolkit running on your IBM i build server.?The build is performed using the IBM i user specified in the build engine.?Use the convenience?Test Connection?button to verify the connection to the Build Server Toolkit running on your IBM i build server.

2.??Create a project area of type scrum, or any other type.?Ensure that the user specified in the toolkit (TestJazzAdmin1?in this example) is a member of this project area.?Ensure also that the user has the required project area permissions to create work items, create snapshots, access search paths, etc.

Figure 1: Project Area members

3.?????Import the Maillist application i Project into your workspace. A link to the .zip file containing the Maillist project is included. here:?maillist.zip,?

1. Deliver the project to the workspace created on your behalf when the Project Area was created.

Figure 2:?Share the i Project to your development workspace

?5.?????The?Maillist?application, used in this article, is a simple RPGLE application that provides a 'green screen' interface to a customer mailing list. It consists of objects that are found in a typical?IBM i application. There are program objects, modules and service programs. There are also physical and logical data files, and display files.

Figure 3:?The Maillist i Project

6.?????In addition to the IBM i resources making up the Maillist Application, the Maillist project also contains several resources used in the configuration of the dependency build.?Expand the Maillist project from the?Navigator?view and notice the following resources.

Figure 4:?Dependency resources

Figure 4 explanations:

1. Link - edit files for the Maillist application are found in the?QLNKSRC?source physical file.?They contain build specifications for the programs and service programs: MAILLIST.PGM, MLGMTNS.SRVPGM, and MLGRPTS.SRVPGM.?Link - edit support is described in more detail later.
2. The setupMailList.xml Ant script.?All the System Definitions used in building the Maillist application are created by this script.?This script also assigns language definitions and target libraries to the SCM resources; it does so via enterprise extension properties.

7.?????Run the setupMailList.xml Ant script by right clicking the script from the?Navigator?view and selecting "Run as -> Ant Build ...".??From the?JRE?tab, make sure to select the"run in the same JRE as the workspace" option.?In the?Targets?tab, notice the various targets provided in the setupMailList.xml script; the?all?target is selected by default.?To run the script again, the user could select to build the?delete?and?all?targets, in that order.

Figure 5:?setupMailList.xml Ant targets

8.?????The reader is encouraged to read through the setupMailList.xml script.?Understanding this script might help you configure your own dependency build.

?<?xml version="1.0"?>

<!--

??Licensed Materials - Property of IBM

???(c) Copyright IBM Corporation 2012. All Rights Reserved.

???Note to U.S. Government Users Restricted Rights:??

???Use, duplication or disclosure restricted by GSA ADP Schedule?

???Contract with IBM Corp.??-->

<project name="Prototype" default="all" xmlns:ld="antlib:com.ibm.team.enterprise.ibmi.systemdefinition.toolkit">

<description>Sample build script</description>

?<property name="sd.prefix"??value=""/>

?<property name="project.root"??value="../Maillist"/>

<!-- Initialize the system definition generation tool -->

?<ld:init

??????repositoryAddress="${repositoryAddress}"

??????userId="${userId}"

??????password="${password}"

??????projectArea="${projectArea}"

??????/>

<!-- Create resource definitions.??

?Not sure how these will be used since load and object libraries are found?

?in the project properties, and can be overriden by the build definition -->

???<target name="resdefs" description="Create resource definitions">

???????<ld:resdef name="${sd.prefix}sourceLibrary"?

?????????description="my load library"

???????????resourcename="_L"

?????????usagetype="0"/>

??????<ld:resdef name="${sd.prefix}objectLibrary"?

?????????description="my object library"

?????????resourcename="_O"

?????????usagetype="0"/>

???</target>

<!-- Create search paths -->

???<target name="searchpaths" description="Create search paths">

???????<ld:searchpath name="${sd.prefix}searchPath"?

???????????description="Search Path"

??????????resourcedefinitions="${sd.prefix}sourceLibrary,${sd.prefix}objectLibrary"/>

???</target>

??<!-- Create translators -->

???<target name="translators" description="Create translators">

??????<ld:translator name="${sd.prefix}PF" description="PF translator"

???????????commandifobjectexists="CHGPF SRCFILE(&L/&F) SRCMBR(&N) FILE(*CURLIB/&N) OPTION(*EVENTF)"

???????????commandifobjectdoesntexist="CRTPF SRCFILE(&L/&F) SRCMBR(&N) FILE(*CURLIB/&N) OPTION(*EVENTF)"

???????????searchPath="${sd.prefix}searchPath"

??????????outputtype="*FILE">

??????</ld:translator>

??????<ld:translator name="${sd.prefix}LF" description=""

???????????commandifobjectexists="DLTF FILE(*CURLIB/&N), CRTLF SRCFILE(&L/&F) SRCMBR(&N) FILE(*CURLIB/&N) OPTION(*EVENTF)"

???????????commandifobjectdoesntexist="CRTLF SRCFILE(&L/&F) SRCMBR(&N) FILE(*CURLIB/&N) OPTION(*EVENTF)"

???????????searchPath="${sd.prefix}searchPath"

??????????outputtype="*FILE">

??????</ld:translator>

??????<ld:translator name="${sd.prefix}DSPF" description=""

???????????commandifobjectexists="CRTDSPF SRCFILE(&L/&F) SRCMBR(&N) FILE(*CURLIB/&N) OPTION(*EVENTF)"

???????????commandifobjectdoesntexist="CRTDSPF SRCFILE(&L/&F) SRCMBR(&N) FILE(*CURLIB/&N) OPTION(*EVENTF)"

???????????searchPath="${sd.prefix}searchPath"

??????????outputtype="*FILE">

??????</ld:translator>

??????<ld:translator name="${sd.prefix}RPGLE" description=""

???????????commandifobjectexists="CRTRPGMOD MODULE(*CURLIB/&N) SRCFILE(&L/&F) SRCMBR(&N) OPTION(*EVENTF)"

???????????commandifobjectdoesntexist="CRTRPGMOD MODULE(*CURLIB/&N) SRCFILE(&L/&F) SRCMBR(&N) OPTION(*EVENTF)"

???????????searchPath="${sd.prefix}searchPath"

??????????outputtype="*MODULE">

??????</ld:translator>

??????<ld:translator name="${sd.prefix}CLLE" description=""

???????????commandifobjectexists="CRTCLMOD MODULE(*CURLIB/&N) SRCFILE(&L/&F) SRCMBR(&N) OPTION(*EVENTF)"

???????????commandifobjectdoesntexist="CRTCLMOD MODULE(*CURLIB/&N) SRCFILE(&L/&F) SRCMBR(&N) OPTION(*EVENTF)"

???????????searchPath="${sd.prefix}searchPath"

??????????outputtype="*MODULE">

??????</ld:translator>

??????<ld:translator name="${sd.prefix}CLP" description=""

???????????commandifobjectexists="CRTCLPGM PGM(*CURLIB/&N) SRCFILE(&L/&F) SRCMBR(&N)"

???????????commandifobjectdoesntexist="CRTCLPGM PGM(*CURLIB/&N) SRCFILE(&L/&F) SRCMBR(&N)"

???????????searchPath="${sd.prefix}searchPath"

??????????outputtype="*PGM">

??????</ld:translator>

??????<ld:translator name="${sd.prefix}SRVPGM" description="" introspection="true"

?????????commandifobjectexists="UPDSRVPGM SRVPGM(*CURLIB/&O) EXPORT(*ALL) &MODULE_ATTRIBUTE &BNDSRVPGM_ATTRIBUTE"

?????????commandifobjectdoesntexist="CRTSRVPGM SRVPGM(*CURLIB/&O) EXPORT(*ALL) &MODULE_ATTRIBUTE &BNDSRVPGM_ATTRIBUTE"

???????????searchPath="${sd.prefix}searchPath"

??????????outputtype="*SRVPGM">

?????????<ld:variable name="MODULE_ATTRIBUTE" value="MODULE(defaults)"/>

?????????<ld:variable name="BNDSRVPGM_ATTRIBUTE" value=""/>

??????</ld:translator>

??????<ld:translator name="${sd.prefix}PGM" description="" introspection="true"

?????????commandifobjectexists="UPDPGM PGM(*CURLIB/&O) &MODULE_ATTRIBUTE &BNDSRVPGM_ATTRIBUTE BNDDIR(&BNDDIR)"

?????????commandifobjectdoesntexist="CRTPGM PGM(*CURLIB/&O) &MODULE_ATTRIBUTE &BNDSRVPGM_ATTRIBUTE BNDDIR(&BNDDIR)"

???????????searchPath="${sd.prefix}searchPath"

??????????outputtype="*PGM">

?????????<ld:variable name="MODULE_ATTRIBUTE" value="MODULE(defaults)"/>

?????????<ld:variable name="BNDSRVPGM_ATTRIBUTE" value="BNDSRVPGM(defaults)"/>

?????????<ld:variable name="BNDDIR" value="*none"/>

??????</ld:translator>

???</target>

???<!-- Create language definitions -->

???<target name="langdefs" description="Create language definitions">

???????<ld:langdef name="${sd.prefix}Build_Referenced_Files" translators="${sd.prefix}PF" languagecode="PF" >

??????????<ld:dependencytype name="PF External file" translators="${sd.prefix}PF"/>

?????????<ld:scanner name="com.ibm.teamp.ibmi.metadata.scanner.dds.pf"/>

??????</ld:langdef>

???????<ld:langdef name="${sd.prefix}Build_Physical_Files" translators="${sd.prefix}PF" languagecode="PF" >

??????????<ld:dependencytype name="PF External file" translators="${sd.prefix}PF"/>

?????????<ld:scanner name="com.ibm.teamp.ibmi.metadata.scanner.dds.pf"/>

??????</ld:langdef>

???????<ld:langdef name="${sd.prefix}Build_Logical_Files" translators="${sd.prefix}LF" languagecode="LF" >

??????????<ld:dependencytype name="LF External file" translators="${sd.prefix}LF"/>

?????????<ld:scanner name="com.ibm.teamp.ibmi.metadata.scanner.dds.lf"/>

??????</ld:langdef>

???????<ld:langdef name="${sd.prefix}Build_Display_Files" translators="${sd.prefix}DSPF" languagecode="DSPF" >

??????????<ld:dependencytype name="DSPF External file" translators="${sd.prefix}DSPF"/>

?????????<ld:scanner name="com.ibm.teamp.ibmi.metadata.scanner.dds.dspf"/>

??????</ld:langdef>

???????<ld:langdef name="${sd.prefix}Build_RPG_Modules" translators="${sd.prefix}RPGLE" languagecode="RPGLE" >

??????????<ld:dependencytype name="RPGLE COPY" translators="${sd.prefix}RPGLE"/>

??????????<ld:dependencytype name="RPG External File" translators="${sd.prefix}RPGLE"/>

??????????<ld:dependencytype name="RPG External Data" translators="${sd.prefix}RPGLE"/>

??????????<ld:dependencytype name="RPGLE SQL INCLUDE" translators="${sd.prefix}RPGLE"/>

??????????<ld:dependencytype name="RPG COPY" translators="${sd.prefix}RPGLE"/>

??????????<ld:dependencytype name="RPG SQL INCLUDE" translators="${sd.prefix}RPGLE"/>

??????????<ld:scanner name="com.ibm.teamp.ibmi.metadata.scanner.RPGLE"/>

???????</ld:langdef>

???????<ld:langdef name="${sd.prefix}RPG_Include_Files(no_translators)" translators="" languagecode="RPGLE">

??????????<ld:scanner name="com.ibm.teamp.ibmi.metadata.scanner.RPGLE"/>

???????</ld:langdef>

??????<ld:langdef name="${sd.prefix}Build_CL_Modules" translators="${sd.prefix}CLLE" languagecode="CLLE" >

??????????<ld:dependencytype name="ILE CL External file" translators="${sd.prefix}CLLE"/>

?????????<ld:scanner name="com.ibm.teamp.ibmi.metadata.scanner.ILECL"/>

??????</ld:langdef>

??????<ld:langdef name="${sd.prefix}Build_CL_OPM_Programs" translators="${sd.prefix}CLP" languagecode="*CLP" >

??????????<ld:dependencytype name="OPM CL External file" translators="${sd.prefix}CLP"/>

?????????<ld:scanner name="com.ibm.teamp.ibmi.metadata.scanner.OPMCL"/>

??????</ld:langdef>

??????<ld:langdef name="${sd.prefix}Build_SRVPGM" translators="${sd.prefix}SRVPGM" languagecode="SRVPGM" >

??????????<ld:dependencytype name="SRVPGM External file" translators="${sd.prefix}SRVPGM"/>

??????????<ld:dependencytype name="SRVPGM Export file" translators="${sd.prefix}SRVPGM"/>

?????????<ld:scanner name="com.ibm.teamp.ibmi.metadata.scanner.SRVPGM"/>

??????</ld:langdef>

??????<ld:langdef name="${sd.prefix}Build_PGM" translators="${sd.prefix}PGM" languagecode="PGM" >

??????????<ld:dependencytype name="PGM External file" translators="${sd.prefix}PGM"/>

?????????<ld:scanner name="com.ibm.teamp.ibmi.metadata.scanner.PGM"/>

??????</ld:langdef>

???</target>

???<!-- Resolve metadata -->

???<target name="resolvemetadata" description="Resolve metadata">

??????<ld:filemetadata>

?????????<ld:filemetadatarule match="/MLGMTNS\.SRVPGM\.eelnk$" name="team.enterprise.build.var.MODULE_ATTRIBUTE" value="MODULE(MLGMTNC MLGMTNR MLGNAMR)"/>

?????????<ld:filemetadatarule match="/MLGMTNS\.SRVPGM\.eelnk$" name="team.enterprise.build.var.BNDSRVPGM_ATTRIBUTE" value="BNDSRVPGM()"/>

?????????<ld:filemetadatarule match="QSRVSRC/.+\.BNDSRC$" name="team.enterprise.build.alwaysload" value="true"/>

??????</ld:filemetadata>

??????<ld:resolvemetadata sourcelibrary="${sd.prefix}sourceLibrary" objectlibrary="${sd.prefix}objectLibrary">

???????????<ld:langdefrule match="QDDSSRC/MLGREFP\.PF$" languagedefinition="${sd.prefix}Build_Referenced_Files"/>

???????????<ld:langdefrule match="QDDSSRC/.+\.PF$" languagedefinition="${sd.prefix}Build_Physical_Files"/>

???????????<ld:langdefrule match="QDDSSRC/.+\.LF$" languagedefinition="${sd.prefix}Build_Logical_Files"/>

???????????<ld:langdefrule match="QDDSSRC/.+\.DSPF$" languagedefinition="${sd.prefix}Build_Display_Files"/>

???????????<ld:langdefrule match="QCLSRC/.+\.CLLE$" languagedefinition="${sd.prefix}Build_CL_Modules"/>

???????????<ld:langdefrule match="BUILD/.+\.CLLE$" languagedefinition="${sd.prefix}Build_CL_Modules"/>

???????????<ld:langdefrule match="BUILD/.+\.CLP$" languagedefinition="${sd.prefix}Build_CL_OPM_Programs"/>

???????????<ld:langdefrule match="QRPGLESRC/.+\.RPGLE$" languagedefinition="${sd.prefix}Build_RPG_Modules"/>

???????????<ld:langdefrule match="QRPGLEINC/.+\.RPGLE$" languagedefinition="${sd.prefix}RPG_Include_Files(no_translators)"/>

?????????<ld:langdefrule match="QLNKSRC/.+\.PGMSRC$" languagedefinition="${sd.prefix}Build_PGM"/>

?????????<ld:langdefrule match="QLNKSRC/.+\.SRVPGMSRC$" languagedefinition="${sd.prefix}Build_SRVPGM"/>

??????</ld:resolvemetadata>

???</target>

<!-- Set source code data.?Not required when LINK-EDIT scanners are in place. -->

???<target name="sourcecodedata" description="Set source code data">

??????<ld:sourcecodedata/>

???</target>

<!-- Delete existing data set definitions, translators and language definitions -->

???<target name="delete"?

??????description="Delete existing data set definitions, translators and language definitions">

??????<ld:deletelangdefs/>

??????<ld:deletetranslators/>

??????<ld:deletesearchpaths/>

??????<ld:deleteresdefs/>

??????<ld:resolvemetadata clean="true"/>

???</target>

????<!-- Export system definitions to an XML file -->

???<target name="export" description="Export">

??????<ld:export file="C:/tmp/exported.xml"/>

???</target>

???<!-- full build -->

???<target name="all" depends="resdefs,searchpaths,translators,langdefs,resolvemetadata,sourcecodedata" description="full build"/>?

</project>

?9.?????The execution of the Ant script should have resulted in the creation of several Enterprise Extensions System Definitions; details of these will be presented in the next section.?The script should also have resulted in the assignment of Language Definitions to several source members via SCM properties.?The SCM property changes should appear in the?Pending Changes?view.

Figure 6: Setup script assigns Language Definitions via SCM properties

10.??Check-in and deliver the changes.

11.??Create a new build definition by right-clicking the?Builds?node under the project area and selecting?New Build Definition....?Select?Create a new build definition?form the ensuing dialog and click?Next.?Notice that there are several IBM i specific build templates.??This article focuses on the?IBM i Dependency Build - Rational Build Agenttemplate.

?Figure 7:?IBM i build templates

Notice also that the?IBM i Build Specification?template is now marked as deprecated.?You can still create new build definitions with it; the "deprecated" qualifier applies to there being no plans to enhance this template and of its possible removal in a future RTC release.

12.??Create and save a build definition of type?IBM i Dependency Build - Rational Build Agent.?The editor contains five tabs – cycle through them to get familiar with what each tab contains.?

• In the?Overview?tab -?ensure to select the build engine created in step 1.
• The?Properties?tab contains no properties by default.
• Tip:?larger builds may fail to build due to a Rational Build Agent timeout error.?The default value in the IBM i build agent is 300 seconds; add a?_TIMEOUT?property to override this value when required.
• In the?Jazz Source Control?tab select your build workspace (?use of?a dedicated build workspace is highly recommended), specify a load IFS folder, and specify your own resource prefix.

Figure 8:?The?Jazz Source Control?tab

Note that the prefix ("AROD" in this example) specified in this tab will be appended to your target library values to form the library names. The setupMailList.xml script included in the zip file uses "_L" and "_O" for load and object libraries; hence the load and object libraries used in the build will be AROD_L, and AROD_O.

o??In the?IBM i Dependency Build?tab - verify that the all LD's appear and are in the correct order (as specified in the "langdefs" target of the setup script).?Also verify that the Ant argument value defaults to "-verbose".?Notice that?Trust Outputs?is enabled by default, notice also that the?Fail on Errors?section default to stopping the build when IBM i command errors or compile errors meet or exceed severity levels of 40.

Figure 9:?The?IBM i Dependency Build?tab

Click the?Dependency Options?tab.?Notice that the defaults are to build the entire workspace, and to?Build changed items only.

Figure 10:?Dependency Options

This concludes the dependency setup.?In the next section the various artifacts and concepts used in IBM i dependency builds will be further explored.

Introduction to IBM i dependency build artifacts and concepts

Part of the function of the setup script is to create the IBM i system definitions required to build the Maillist application as depicted in the following screen capture.

Figure 11:?IBM i system definitions created by the setupMailList.xml script

The script also assigns language definitions to SCM resources via Enterprise Extension properties, for example:

Figure 12:?Language definitions are assigned to SCM resources via Enterprise Extensions properties?

Language Definitions contain dependency build information such as the list of translators (translators are described later) used in building the SCM resource.?As shown in the following figure the set up script created the "Build_RPG_Modules" language definition editor to use only the "RPGLE" translator.

Figure 12a: The?Language Definition?editor

Language Definitions also contain the?Source Code Scanners?used to collect the Source Code Data dependencies for the associated SCM resource(s), and the supported scanned?Dependency Types.??

Figure 12b: The?Scanners?tab of the?Language Definition?editor

Translators define the remote commands to be used at build time.?The command used can be based on whether the object exists.

Figure 13:?RPGLE translator?

Notice the use of?Variables?in the translator command strings (see Figure 13).?Variables have the following characteristics:

1. Variables appear in command lines preceded by the "&" symbol.?A variable name is terminated by a white space or an optional ".".?The optional "." can be used in the cases where you want the variable value to be immediately followed by a non white space character.
2. Example: "&DAY.DAY" could expand at build time to "MONDAY"
3. There are several special variables as shown in the following table.??

?Name ?Description ? Usage

&F Physical file name (internal)

&L Library name (internal)

&N Member name (internal)

&X Object description (internal)

&SRCLIB Source library (internal)

&OBJLIB Object library (internal)

&SP Search path (internal)

&O Output name (internal)

&*_ATTRIBUTE Values gathered from link-edit files. (calculated)

1. User variables must have their default values assigned in the translator.
2. Variable values can be overridden at two places:

• At the SCM level via Enterprise Extensions.?Values entered here have highest precedence.

• Figure 14:?Variable override through EE properties
• ?At the build definition level.?Values entered here have second highest precedence.?Notice that variables are entered in the standard?Properties?user interface, as such their names must be qualified with the prefix "team.enterprise.build.var.".

Figure 15: Variable override through Build Definition properties

1. Variable substitution occurs at build time.?The user can examine the expanded command strings in the build log.?The following image depicts the variable substitution that takes place at build time with the RPGLE translator.?The highlighted portion depicts the command as specified in the Translator, the text underneath is the expanded command string as found in the build log.

Figure 16:?Variable substitution

Link - Edit?file support is another important concept in IBM i dependency builds.?Link - Edit support allows the user to specify command attributes in source members.

1. This support is implemented as an extension of our variable support.?Link - edit variable names should use the "_ATTRIBUTE" suffix.?To participate in Link - Edit support a translator should have the?Inspect built object and update build map?option selected, as illustrated below..

1. Notice the commands in the PGM translator, shown above.?They each make use of a couple of link-edit variables.
2. Users can specify attribute values in their SCM source files.?The following screen capture illustrates how two such attribute values could have been defined in a source member.

1. Attributes can be referenced as variables in Translator commands

1. Attribute variables used in command strings are substituted with the corresponding mined attribute values at build time.?Expanded command strings can be found in the build log file.

The next section will demonstrate how builds are invoked and how results can be examined.

Performing builds and examining results.

The section demonstrates the build support for the new IBM i dependency build template in the Rational Team Concert product.?A build will be submitted and the build results will be examined.

1. Submit the build.??Right-click the build definition, select?Request Build…., and click?Submit?on the ensuing dialog.
2. Wait for the build to complete then open the build results.?Switch to the?Builds?view, wait until the progress shows “Completed” then open the results by double clicking the build line.

Figure 17:?The?Builds?results view

1. Examine the build results.?Notice that the results page contains several tabs.?Cycle through them to get familiar with what each tab contains.?

• ??The?Overview?tab contains summary information and convenience links to other tabs.?Notice that the text next to?Build report:?identifies the number of objects built.

o??The?Activities?tab contains timing information.

o??The?Compilation?tab contains compilation results.?You can use this tab to work with compile errors and warnings.

o??The?Downloads?tab contains links to the generated Ant scripts and properties files used during the build.

o??The?Logs?tab contains pointers to the log file(s).

o??The?External Links?tab contains a link to the build report and to each of the buildmaps when?Publish buildmap links?is selected in the build definition.?Click thebuildReport.xml?link in this tab to view the build report in a browser view.?Individual buildmaps are a click away, see links to them in the?Output?column.

Figure 18: The new Build Report

1. You can use RDi to examine what was built.

• Switch to the?Remote Systems Explorer?perspective.?Locate your output library in the?Remote Systems?view, right click it and select?Show in Table.

• Figure 19:?Show in Table?action.
• You can customize the?Object Table?view to include the?Last Modified?column.?Click the?Last Modified?column title twice to have the results ordered chronologically in descending order.?We will re-use this view to help us identify which objects were created during incremental builds.?From this order the user can infer the order in which objects were built.

Figure 20: Ordered output library contents in?Object Table?view.

Incremental builds

In this section we’ll modify a Display File source member, deliver the change, and then perform a build.?Performance of incremental build scenarios with this new build template should be better than with the Build Specification template.?The build should only create the affected output objects and complete a lot faster than the complete build.

1. Make and deliver a change to the MLGINQD.DSPF source member,
2. This change should result in the rebuilding of three objects:
3. The MLGINQD DSPF object,
4. The recompilation of MLGINQR.RPGLE (see SCD information for the MLGINQR.RPGLE member in figure 32)
5. And the re-binding of the MAILLIST.PGM program.
6. A handy way to determine what will be built is to perform a preview build.?

o??This can be accomplished from the Request Build wizard as illustrated by the following screen capture.

Figure 21: The?Request Build?wizard

o??Click submit and notice the following

o??The builds view should display.?The Builds view identifies this build as a preview build.

Figure 22: The?Builds?view

o??Open the build report by opening the build results and then clicking on the?buildReport.xml?link from the?External Links?tab of the build results editor.

Figure 23: Link to build report

o??Notice that the report can be used to identify the objects that would have been built.?As expected, three objects are identified.?The report also allows the user to examine the dependency set for each buildable resource with a?reason to build?less than 6; the screen capture below shows the dependencies for the MLGINQD DSPF object????expanded.

Figure 24: The Preview build report

The?Reason to build?codes are explained at the end of the report.

Figure 24A: Reasons to build

1. Perform the actual incremental build.

• Locate the build definition in the?Team Artifacts?view.
• Submit build by right clicking build definition and selecting?Request Build….?Click?Submit.
• Wait for the build to complete.

1. Use several methods to verify that only the expected items were built.
2. Open the build results (by double clicking the build result from the?Builds?view).?Notice, in the?Overview?tab, that the number of files processed was 3; indicating that translators processed three input resources.

1. Figure 25: The?Overview?tab
2. Proceed to the?Compilation?tab.?Notice that display file member MLGINQD, and RPG member MLFINQR were compiled as expected:

Figure 26: The?Compilation?tab

1. Switch to the?External links?tab and click the?buildReport.xml?link in this tab to view the build report.?Notice that only three items were built.

Figure 27: The new build report

1. Switch to the?Remote Systems Explorer?perspective.?Locate your output library in the?Remote Systems?view, right click it and select?Show in Table.?Order the list in descending chronological order, and notice that three objects were modified by the build appear at the top.?Notice also that the order the objects were built can be inferred from this table (DSPF,?MODULE, and *PGM).

1. Figure 28: *Object Table?view showing built objects in chronological order

Working with Source Code Data

Dependency builds rely on data collected by the source code data (SCD) collection service in the Rational Team Concert server.??

SCD scanning occurs either asynchronously (default is every hour) or synchronously when you invoke builds or manually reset the SCD in a stream.?Your system administrator can control several aspects of the SCD collection via the Web interface using the "..../ccm/admin" URL, select Advanced properties and locate the Source Code Data section:

Figure 29: SCD configuration through advanced properties?

Note: the maximum number of files in SCD defaults to 1000; you will need to bump this value up if the number of source files in your projects exceed this value.

Rational Team Concert Enterprise Extensions provides several source scanners for the IBM i platform.?Scanners are associated to language definitions.

Figure 30: IBM i SCD scanners?

Use the?Source Code Data?branch under?Enterprise Extensions?in the?Team Artifacts?view to control and monitor data scanning on your streams.?The following screen capture illustrates the actions available. You can use these actions to select which streams to scan, to manually update or reset scanned information, or to create queries.

Figure 31: SCD actions?

There are several ways to inspect the scanned Source Code Data.

1. One way is to use the SCD editor. Locate the member of interest in a resource view, suach as the?i Projects Navigator?view.?Right click it and select?Enterprise Extensions -> Open Source Code Data Editor.

Figure 32: The?Source Code Data?editor

The section titled?Dependency Properties?shows the mined dependencies for the selected member.?Notice also a section entitled?User-defined Data; any additions made here are persisted even when the streams are re-scanned.?This is where users would introduce manual dependencies.??Entering dependencies manually would be required in cases where there are no scanners applicable to the resource, or when the scanners are unable to determine a dependency by just scanning the source file.

1. Another way to inspect SCD is through impact analysis.?Locate a member?in the?i Projects Navigator?view.?Right click it and select?Enterprise Extensions -> Impact Analysis….?You can select to display the list of objects that depend on the selected resource, or the list of objects that the selected resource depends on.?Select?Show files that this file depends on?from the resulting dialog, and click Finish.
2. The results are displayed in the?Source Code Data?view, as shown in the following image. Notice that the information line (shown highlighted in Figure 33) in the view summarizes the result of your impact analysis.

Figure 33: The Source Code Data view

1. Yet another way to view SCD is via queries.?To create a query right click?Source Code Data?and select?New Query ….
2. To show all resources that contain dependencies of type INCL, you can configure the query as follows.?Notice that a convenience?Run?button is provided to allow you to test the query as it is being developed.

Figure 34:?Source Code Data Query?editor,?Conditions?tab.

The?Result Layout?tab in the query editor allows you to configure which columns to display and how to sort the results.

Figure 34a:?Source Code Data Query?editor,?Result Layout?tab.

Summary

The objective of this article was to demonstrate the new IBM i dependency build template introduced in Rational Team Concert.