How to set up a Rational Team Concert Dependency Based Build for z/OS
Rational Team Concert z/OS dependency builds is a build capability that through source code data scanners is able to determine what needs to be compiled since last successful build in a target execution environment. This article describes how to set up a zOS build environment to produce executable for two different execution environments from source files contained in a source repository.
1. Requirements
Set up a zOS build environment to produce executable for two different execution environments from source files contained in a source repository.
2. Introduction to RTC z/OS dependency builds
RTC z/OS dependency builds is a build capability that through source code data scanners is able to determine what needs to be compiled since last successful build in a target execution environment. Some key concepts:
1. Translator: Describes an operation that will be performed on a file during a build. It can be either a called program (MVS module) for compilation (e.g. IGYCRCTL for COBOL compilation) or an ISPF/TSO command.
2. Language Definition: Represents the type of source file. For example: Cobol, Cobol CICS, etc. Every source file contained in the repository should have a language definition associated with it. A single language definition can contain one or more translators or build properties for describing build operations. A language definition may not include translators. For example, typically the language definition for COBOL copybooks does not have translators and such language definitions are used only for source code scanners.
3. Build Definition: Describes a Jazz team build. Build definitions used for RTC z/OS dependency builds are created based on Dependency Build definition template. A dependency build definition contains the list of language definitions that will be processed in the build. When the language definitions selected in the build definition are using build properties for describing build operations, such build properties need to be defined in the build definition so that RTC build runtime code can substitute actual translators used in the build for them.
3. Solution
We will utilize build properties in language definitions to describe operations that will be performed during a build. Then two build definitions, which corresponds to two execution environments, will substitute different translators for those properties in order to produce two different executables.
As showed in the picture below, there is a language definition "Cobol Batch Demo", a source file "EXAMPLE.COB", two build definitions "Build Definition Demo INT (ARIN)" and "Build Definition Demo PROD (AREX)" each one represents a different target environment. The "Cobol Batch Demo" language definition contains four build properties, for which RTC build runtime substitutes translators. Within each build definition for "Cobol Batch Demo" a different set of translators are used for defining those build properties.
In the "Build Definition Demo INT (ARIN)" build definition, which is for the integration environment, four build properties for "Cobol Batch Demo" are defined as:
1. "Dummy Step Translator"
2. "Compilation Cobol Batch ARIN Translators"
3. "Linkedit Batch ARIN Translator"
4. "Dummy Step Translator"
while in the "Build Definition Demo PROD (AREX)" build definition, which is for the production environment, has four build propertie definitions for "Cobol Batch Demo" as:
1. "Copy Cobol Batch Executables to Backup AREX Translator"
2. "Compilation Cobol Batch AREX Translator"
3. "Linkedit Batch AREX Translator"
4. "Log promotes BATCH Translator"
By defining those build properties, two different sets of translators will be used in two different build definitions even though the same language definitions are used regardless of build environment where executables are generated.
4. Example
We are going to describe the detailed steps to configure an RTC z/OS dependency build to build Cobol sources files into two different execution environments. In the following example, two environments (Integration and Production) are used, but the same approach can be applicable to the situations where there are environments need to be supported.
4.1. Create a Language Definition
A language definition can define the default extension (to differentiate source types Cobol, Cobol CICS, etc.) and the ordered list of translators that are going to be used to build the source files that belong to that language.
In the example, illustrated in the image below, is shown the definition of language "Cobol Batch Demo, extension "cob" and the list of build properties, for which will be substituted translators in a build.
1. ${demo.build.translator.copymbrb}: Backup the existing load module file in the backup destination library before overwriting with the new one.
2. ${demo.build.translator.cobolbatch}: Compile Cobol batch source file
3. ${demo.build.translator.lkedbatch}: Link Edit Cobol batch binary file
4. ${demo.build.translator.copylogbatchaz}: Register the files generated in a log.
Note that build properties are shown by a name enclosed by "${" and "}" in the Translator list. The order in the list is relevant as they are going to be executed in the order defined to build the source file.
File extension is important because the build process (sequence of translators) defined for language "Cobol Batch Demo" just apply to the files with extension "cob" stored in RTC SCM unless a file is associated with a language definition explicitly though a file property. File extensions are used in RTC to differentiate the kinds of source types (Cobol Batch, Cobol Batch DB2, Cobol CICS, etc.) and their build process (sequence of translators). A different language definition and extension for each source type should exist.
In the following table below, it can be found some examples of Languages Definitions and extensions associated with them.
| Language Definition | Extension |
| Cobol Batch Demo | cob |
| Cobol CICS Demo | coc |
| Cobol DB2 Demo | cod |
4.2. Create one Dependency build definition per execution environment
A dependency build definition, as shown in the image below, represents a z/OS target environment, a workspace with the source files to be built in the target environment and properties to build like translators to be used within the process.
As there are two different execution environments, one build definition "Build Definition Demo INT" is created for the target execution environment "Integration environment". The properties defined are,
1. ${demo.build.translator.copymbrb}: Paso Dummy (does nothing IEFBR14)
2. ${demo.build.translator.cobolbatch}: Compilation Cobol Batch ARIN (Integration)
3. ${demo.build.translator.lkedbatch}: Linkedit Batch ARIN (Integration)
4. ${demo.build.translator.copylogbatchaz}: Paso Dummy (does nothing IEFBR14)
5. Entorno (Environment): INT
Another build definition "Build Definition Demo PROD" for the "Production Environment". The build properties for the translators defined are different.
1. ${demo.build.translator.copymbrb}: Copy Cobol Batch Executable to Backup AREX (Copy executable to backup before overwriting)
2. ${demo.build.translator.cobolbatch}: Compilation Cobol Batch AREX (Production)
3. ${demo.build.translator.lkedbatch}: Linkedit Batch AREX (Production)
4. ${demo.build.translator.copylogbatchaz}: Genera LOG promotes BATCH AZAM (generate compiled source file LOG)
5. Entorno (Environment): PROD
4.3. Define Translators
Source files of language "Cobol Batch Demo" for production environment (Build Definition Demo PROD) have a sequence of 4 translators.
1. Copy Cobol Batch Executables Backup AREX (for the build property demo.build.translator.copymbrb) This is a translator that invokes a REXX script as an ISPF command (see the screen shot). The purpose of this translator is to copy executable files from the production library into a backup library. In case something goes wrong with the current compilation of the source to production there is a copy of the executable in the backup library to restore.
The command to call the REXX as shown in the image is
EXEC 'TREX.ISPF.CMDPROC(RADCOPMB)' 'AREX.LBBATCH.LOADLIB AREX.LBBATCH.LOADLIB.BACKUP @{source.member} REPLACE '1. TREX.ISPF.CMDPROC(RADCOPMB): Location of REXX script
2. AREX.LBBATCH.LOADLIB: Source library parameter
3. AREX.LBBATCH.LOADLIB.BACKUP: Target library parameter
4. @{source.member}: This is replaced by the name of the file being built
5. REPLACE: Option parameter to replace the binary if already exists in the backup library
The REXX script uses ISPF commands like
Initialization of PDS
ISPEXEC LMINITFree of PDS
ISPEXEC LMFREECopy of members between data sets with REPLACE option if already in target PDS.
ISPEXEC LMCOPY
2. "Compilation Cobol Batch AREX" (for the build property demo.build.translator.cobolbatch) This is a called program as illustrated in the image below. The purpose of this program is to compile the source Cobol file in production environment.
1. Called program: "IGYCRCTL" Cobol compiler.
2. Default options for program called: XREF,OFFSET,MAP,LIB,TERM,BUF(20K),NORENT,RMODE(ANY)
3. SYSLIB: List of libraries with COPYBOOKS
4. SYSIN: Source program being compiled
5. SYSLIN: Temporary library to store compiled program
6. SYSPRINT: Temporary library to store SYSPRINT from compilation
7. SYSTERM: Temporary library to store SYSTERM from compilation
Please note:Check "Use for Syntax Check" if you are using RDz in combination with RTC.
3. "LKED Batch AREX" (for the build property demo.build.translator.lkedbatch) This is a translator that invokes a called program as illustrated in the image below. The purpose of this program is to link-edit the binary Cobol generated in the previous step.
1. Called program: "HEWL" link-editor
2. Default options for program called: LIST,XREF,AMODE(31),RMODE(ANY)
3. SYSLIB: List of libraries used for link-edit
4. SYSMOD: The library where linked-edited module is placed
5. SYSLIN: Temporary library where resides the compiled source file
6. SYSPRINT: Temporary library where SYSPRINT is stored
4. "Genera LOG promotes BATCH AZAM" (for the build property demo.build.translator.copylogbatchaz) This is a translator that invokes a REXX script as a TSO command. The purpose of this translator as explained above is to generate a LOG of sources that have been built to audit the process.
The command to call the REXX as shown in the image is
EXEC 'TREX.ISPF.CMDPROC(@RTCLGAZ)' ' @{source.member} B AZAM'1. TREX.ISPF.CMDPROC(@RTCLGAZ): Location of REXX script
2. @{source.member}: This is replaced by the name of the file being built
3. B: Option parameter. B means Batch
4. AZAM: Option parameter. AZAM is the name of the log file to register the members built
The REXX script uses TSO commands like:
ALLOCEXECIOSYSDNSPlease note:Translators for build definition "Build Definition Demo INT" need to be defined following a similar process.
4.4. Create a source file
To create a source file the first thing to do is to create a repository workspace that contains a RTC component, for example, "demoCobolBatch" where files of type "Cobol Batch Demo" or others are going to be stored as illustrated in the image below.
A zComponent Project "ProjectDemoCobolBatch" must be created under eclipse "Resource" view and shared in "demoCobolBatch" component as illustrated in the image below
Once the Project is shared under RTC source control a zFolder must be created under the zComponent Project "ProjectDemoCobolBatch" as illustrated in the image below
Finally, under the zFolder "COB" the zFile is created, "EXAMPLE.cob", and associated with the Language Definition "Cobol Batch Demo". Note that extension "cob" is important to be set on the file name as illustrated in the image below
The file can be edited offline from Z system without RDz as illustrated below or
In combination, with RDz source file can be loaded on Z system and edited online to benefit from all the capabilities of RDz as code content assistance,debugging, etc.
To work with RDz a z/OS Project should be created on RDz z/OS perspective and "ProjectDemoCobolBatch" files loaded on the Z system as illustrated in the image below.
4.5. Execute a Build definition request
Request a build of "Build Definition Demo INT" for Integration or "Build Definition Demo PROD" for Production.
If "Personal Build" is checked it is possible to select
1. Workspace to build: workspace where the component created has been stored
2. Load directory: temporary directory on USS required tostore metadata during build process
3. Data set prefix: data set prefix where to allocated sources to be build. In the example ARDE.ST.RTC
When build is run,
1. A PDSE is created if not exists ARDE.ST.RTC.COB (to allocate the zFolder COB)
2. A member EXAMPLE is created on PDS ARDE.ST.RTC.COB(EXAMPLE) (to allocate zFiles modified to rebuild from last successful build)
3. Once the source is allocated to the PDSE, the build process conducted by the sequence of translators defined for language definition "Cobol Batch Demo" is executed to build the source file. If build is successful and there are no changes next build request sources are not built.
Rebuild just what has been changed since last successful build is the principle of dependency builds!
Please note:If "Personal Build" is not checked default options defined on build definition as illustrated in the image below are used
For more information
About the author
Luis Bazo Garcia is an Expert Certified IT Specialist in the area of development tools working for IBM Spain since 2006 He can be contacted at luis.bazo@es.ibm.com.
Copyright © 2012 IBM Corporation
Yes