Introduction
This article presents a way to use the RBD build server to perform builds on files maintained in an RTC repository. In this scenario, an RTC user can set up a build definition and use an Ant build script to invoke the build technology used by RBD for builds on the z/OS system.
The files to be built are not necessarily generated by EGL.
The mechanism is general enough so that it is not restricted to a particular language like COBOL or translator operation.
Prerequisites
This method uses the RBD Build Server and Buiild Client included in RBD. The Build Server is part of the Rational COBOLRuntime program product and has to be installed on the target z/OS system. The Build Client is an executable named ccubldc and is installed on the RBD client.
It is necessary to have a good understanding of how the RBD Build Server works in order to set up the necessary configuration. An overview is provided in this document and details can be found in the RBD information center.
Overview of the RBD Build for z/OS
The RBD Build Server is a program that runs on z/OS, listening on a TCP/IP port. It receives build requests from clients on Windows or Linux platforms. A build request includes the name of a build script. The build script contains all the information that the Build Server needs in order to translate the input source files to the target object (for example translate a C source file to a load module).
The build scripts typically reside on PDS on the z/os system, but can be optionally transferred from the client during the build event also.
Following is a sample build client request, showing only the key parameters:
ccubldc –h HOST@PORT –b COBCOMP -it MYPROG.cobol
Here the build client is sending the file MYPROG.COBOL to the server (myhost.com) over TCP/IP port 1234, where the server is to run the build script named COBCOMP. The build script has the information on where to place the source file during the build, and what to do with it during the request process (for example Compile and then Link).
In the sample Ant script provided below more detailed examples of ccubldc usage are provided.
Advantages of using the RBD Build Server
This is an alternate method for RTC z/OS users, who also have access to RBD, to perform builds
The main advanatge of using the RBD Build Server is the simplicity of the configuration needed toperform the builds. It is assumed of course that the build server is already running as part of the RDB runtime. To perform RTC builds one will have to define the build scripts on the z/OS system, and configure a build engine and build defintion to submit builds against a workspace.
The build scripts, which run the translator function like compile and link are typically set up on the z/OS machine. These are relatively easy to set up and can be reused for different users, simplifying the configuration.
Limitations
Using the RBD Build Server for performing build on files in an RTC workspace relies on the Jazz Build Engine running on the client side. Therefore, it cannot be used to perform dependency builds.
Configuration Details
The method that performs the z/OS build, using the RBD Build Server, is depicted in the following diagram.
In order to perform the build using the RBD Build Server, the following setup steps are needed.
1. Define the Build Engine (RTC Client)
The following is a sample Build Engine. Note that some of the build properties that will be used by the ccubldc client are defined here.
2. Define the Build Definition (RTC Client)
3. Create the Ant Script and make it accessible to the Build Engine process
The Ant Script performs the basic task of managing the build. It has to be designed for your particular scenario, and its complexity will depend on what is needed.
In the provided sample. the Ant Script is designed to retrieve all the files from the workspace using the "teamFetch" predefined RTC Ant task. After this is done the script locates all the COBOL copy members and uploads them to a PDS, using a call to ccubldc client. The script then locates each COBOL source file and invokes ccubldc to get the source compiled on the host machine.
The contents of the sample Ant script are provided later in this document.
4. Define the Needed Buld Scripts on the Host Machine (z/OS Server)
The build scripts used by the Ant script need to be created. It is best to create a partitioned dta set on the host system containing the build scripts, and refer to it using the PROCLIB parameter. It is necessary to understand the logic of build scripts. The build scripts supplied with the Rational COBOL Runtime product are tailored for compiling and linking COBOL programs generated from EGL. These can be found in the SELASAMP library on the host and can be used as samples to facilitate learning.
However, for general builds which are not for EGL generated cobol programs, you will need to create your own build scripts.
An RBD build script is a file written in pseudo-JCL language, which is similar to regular z/OS JCL, but with some modifications. It contains one or more executable steps which invoke a program to run. The input and output datasets are defined using Data Definition (DD) statements similar to JCL, but with optional added keywords CCUEXT which inidicate to the Build Server if the file is input or output from the client.
The detailed logic of how build scripts work is descriibed in the RBD infocenter. There are two samples provided in this document.
7. Start the Build Server (z/OS)
6. Start the Build Engine
The Jazz Build Engine process must be started as required by RTC, using the jbe program in the RTC Build System Toolkit. For details, see the RTC infocenter.
7. Request Build (RTC Client)
The RTC client requests a build against the build definition, using the RTC workspace in which the the build source has been developed.
Sample Ant Script
The following sample can be used as a starting point, and will need to be modified as needed to fit your particular requirements.
<?xml version="1.0"?>
<project name="Ant-Test" default="main" basedir=".">
<!-- Sets variables which can later be used. -->
<!-- The value of a property is accessed via ${} -->
<taskdef resource="net/sf/antcontrib/antcontrib.properties">
</taskdef>
<taskdef name="teamFetch"
classname="com.ibm.team.build.ant.task.TeamFetchTask">
</taskdef>
<property name="WorkDirectory" value="."/>
<!-- get the source files -->
<target name="getsrc">
<teamFetch repositoryAddress="${repositoryAddress}"
userId="${userId}"
password="${password}"
workspaceUUID="${workspaceName}"
destination="${WorkDirectory}"
verbose="true" />
</target>
<!-- create a list of .CPY files -->
<target name="createCopyList">
<delete file="file.list"/>
<foreach target="keepFile" param="file">
<path>
<fileset dir="." includes="**/*.cpy" />
</path>
</foreach>
</target>
<target name="keepFile">
<echo file="file.list" append="true" message="${file}${line.separator}" />
</target>
<!-- transfer copy files using ccubldc -->
<!-- NEED TO SKIP THIS STEP IF THERE ARE NO COPY FILES TO TRANSFER -->
<target name="transferCopy" depends="createCopyList">
<exec executable="ccubldc" dir="${WorkDirectory}" failonerror="true">
<arg value="-V" />
<arg value="-h" />
<arg value="${buildHostPort}" />
<arg value="-b" />
<arg value="XFER" /> <!-- dataset specified by -proclib below must contain member XFER. Alternatively, no -proclib and expect server to have the script XFER -->
<arg value="-au" />
<arg value="${buildUserId}" />
<arg value="-ap" />
<arg value="${buildUserPassword}" />
<arg value="-it" />
<arg value="@file.list" />
<arg value="-proclib" />
<arg value="${proclib}" />
</exec>
</target>
<!-- loop on the list of cobol programs found in the work directory-->
<target name="compileAll" depends="transferCopy">
<foreach target="compile1Program" param="file">
<path>
<fileset dir="." includes="**/*.cbl" />
</path>
</foreach>
</target>
<!-- compile one cobol program -->
<target name="compile1Program" >
<basename property="filename" file="${file}" suffix=".cbl"/>
<exec executable="ccubldc" dir="${WorkDirectory}" failonerror="true">
<arg value="-V" />
<arg value="-h" />
<arg value="${buildHostPort}" />
<arg value="-b" />
<arg value="COBCOMP" /> <!-- dataset specified by -proclib below must contain member COBCOMP which compiles a cobol program -->
<arg value="-au" />
<arg value="${buildUserId}" />
<arg value="-ap" />
<arg value="${buildUserPassword}" />
<arg value="-it" />
<arg value="${file}" />
<arg value="-P" />
<arg value="${filename}." />
<arg value="-v" />
<arg value="CHGLQ=MAHADEV" />
<arg value="-proclib" />
<arg value="${proclib}" />
<arg value="-c" />
<arg value="LT" />
<arg value="-n" />
<arg value="8" />
</exec>
</target>
<!-- result files -->
<target name="result">
<artifactFilePublisher repositoryAddress="${repositoryAddress}"
userId="${userId}"
password="${password}"
buildResultUUID="${buildResultUUID}"
filePath="ccubldc.log"
label="build result" />
</target>
<target name="main" depends="getsrc,transferCopy,compileAll">
<description>Main target</description>
</target>
</project>
Sample build scripts
The Ant script above refers to two build scripts- XFER, which is used to transfer the copybook members to a pds on the hose, and COBCOMP, which compiles a given Cobol file. following are samples of each of these.
XFER
This script will transfer any input file with extension of cpy to a predefined PDS named MAHADEV.RTCBUILD.CPY
//XFER EXEC PGM=IEFBR14 1
//DD1 DD DISP=OLD,DSN=MAHADEV.RTCBUILD.CPY2,CCUEXT=CPY3
//
1 Name of program to run in this step
2 PDS MAHADEV.RTCBUILD.CPY is a predfined dataset used by the build server for running this buildscript
3 CCUEXT=CPY indicates that all client files with extension=CPY (case insensitive) will be placed in this PDS before running the steps
COBCOMP
This script will compile any input file with extension cbl.
//**********************************************************************
//* COBCOMP - COBOL COMPILE
//*********************************************************************
//*
//DEFAULTS VARS1 CGHLQ=USER,
// COBCOMP=COBOL.V4R1M0.SIGYCOMP,
// RGN=4096K,
// WSPC=2500
//*
//* PARAMETERS:
//* CGHLQ = COBOL GENERATION USER DATA SET HIGH LEVEL QUALIFIER
//* COBCOMP = COBOL COMPILER LIBRARY
//* RGN = REGION SIZE
//* WSPC = PRIMARY AND SECONDARY SPACE ALLOCATION
//*
//**********************************************************************
//* COMPILE THE COBOL PROGRAM
//**********************************************************************
//C EXEC PGM=IGYCRCTL,3REGION=&RGN,
// PARM='NOSEQ,QUOTE,LIB,RENT,NODYNAM,OPT&DBCS,
// TRUNC(BIN),NUMPROC(NOPFD)
//STEPLIB DD DISP=SHR,DSN=&COBCOMP
//SYSIN DD CCUEXT=CBL2,DISP=(NEW,DELETE),
// UNIT=SYSDA,SPACE=(CYL,(1,5)),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)
//SYSLIB DD DISP=SHR,DSN=&CHGLQ..RTCBUILD.CPY
//SYSLIN DD DISP=SHR,DSN=&CGHLQ..RTCBUILD.OBJECT(&INPUT)4
//* RETURN COMPILER LISTING TO CLIENT AS &INPUT .C.SYSPRINT
//SYSPRINT5 DD CCUEXT=CCUOUT6 ,DISP=(NEW,DELETE),
// UNIT=VIO,SPACE=(CYL,(30,60)),
// DCB=(RECFM=FB,LRECL=133,BLKSIZE=6650)
//SYSUT1 DD SPACE=(800,(&WSPC,&WSPC),,,ROUND),UNIT=VIO
//SYSUT2 DD SPACE=(800,(&WSPC,&WSPC),,,ROUND),UNIT=VIO
//SYSUT3 DD SPACE=(800,(&WSPC,&WSPC),,,ROUND),UNIT=VIO
//SYSUT4 DD SPACE=(800,(&WSPC,&WSPC),,,ROUND),UNIT=VIO
//SYSUT5 DD SPACE=(800,(&WSPC,&WSPC),,,ROUND),UNIT=VIO
//SYSUT6 DD SPACE=(800,(&WSPC,&WSPC),,,ROUND),UNIT=VIO
//SYSUT7 DD SPACE=(800,(&WSPC,&WSPC),,,ROUND),UNIT=VIO
//
1 VARS is a special stement in the build scripts which define the default values of any variable used in the body of the build script. The values of these variables may be overriddennby the ccubldc client using the -v parameter
2 The program to execute in this case is the COBOL compiler
3 The DD definition indicates a temporary dataset for the duration of the build. It could have been a permanent dataset as well as in XFER step
4 &INPUT is predefined variable and in this case is the name of the cobol file sent by the ccubldc client using the -i parameter. The compiled object will be stored in the &CGHLQ..RTCBUILD.OBJECT dataset for future use. Note that the build script could have an addition step which would link-edit the object.
5 SYSPRINT DD initciactes temporary dataset usind by the COBOL compiler for the listing.
6 CCUEXT=CCUOUT indicates that this file is to be retruned to the client upon completion of the build
References
1. For information on RBD builds on z/os, refer to the RBD infocenter, for example:
http://pic.dhe.ibm.com/infocenter/rbdhelp/v8r5m0/index.jsp
Search for 'pseudo-JCL Syntax' for information on creating build scripts.
2. For information on RTC builds, refer to the RTC infocenter, for example:
http://pic.dhe.ibm.com/infocenter/clmhelp/v4r0m3/index.jsp