Lesson 1: Preparing your environment

You must prepare your development environment before you can define builds using Antz.

This lesson assumes that you have performed the following tasks:
  1. Prepared a Jazz Team Server. See com.ibm.teamz.install.doc/topics/rtczinstchap.html for information about installing and configuring the Jazz Team Server.
  2. Created a project area.
  3. Created a user to perform the builds. Edit the user profile and verify that it has the following Client Access Licenses for Rational Team Concert for System z:
    • zDeveloper
    • Build System
  4. Modified the process configuration to enable the user to save data set definitions, language definitions, and translators.
  5. Installed and configured the Rational Team Concert for System z client. The client should have a repository connection defined for your Jazz Team Server, and it should be connected to your project area.
  6. The Jazz Build System should be installed on the z/OS system that performs builds.
  7. The Rational Build Agent should be installed and configured on the z/OS system that performs builds.
Notes:
  1. The Rational Build Agent will be started with a shell script that is described later in this tutorial.
  2. This tutorial does not depend on Job Monitor.

Lesson 2: Configuring the Rational Build Agent shell script

The Jazz Build System contains a sample script named startbfa.sh that you can use to start the Rational Build Agent on your build machine. You can find this script in the pathPrefix/usr/lpp/jazz/v2.0/buildsystem/buildtoolkit/examples/startbfa directory, where pathPrefix is any prefix you specified during SMP/E installation. This script is required for starting the Rational Build Agent to specify the credentials that Rational Build Agent needs to connect to the Jazz Team Server for System z, and also to provide access to libraries needed for Antz and native compilation. If necessary, you can copy this script to a work directory to modify and execute it.

The script must be configured to suit your environment. Replace the variable strings in the sample script as described in the following table:
Table 1. Sample script variable strings
Variable Description
@pathPrefix@ Directory path to prefix the Jazz directory.
Note: This is the prefix to the Jazz directory, so your prefix should include any prefix you specified as part of the SMP/E installation, as well as /usr/lpp.
@javaPathPrefix@ Directory path to the IBM 31-bit SDK for z/OS Java 2 Technology Edition V5
@yourUserid@ The Jazz builder user ID
@yourPasswordFile@ The Jazz password file
@zLang@ Encoding used in host files; for example, IBM-037. If you do not specify a value, the default value determined by your z/OS UNIX environment is used.
@timeout@ Timeout value, in seconds, for build step execution. If you do not specify a value, the default value 300 seconds is used.
@stepLib@ STEPLIB DD to use in your z/OS build; for example, SYS1.LINKLIB:CEE.SCEERUN
@bfaBinPath@ Directory path to the Rational Build Agent executable directory
@bfaConfPath@ Directory path to the Rational Build Agent configuration file directory
@yourHomeDirectory@ Your home directory. Use this only when the HOME environment variable is not defined elsewhere.
Tip: Run the startbfa.sh script when you are ready to start the Rational Build Agent and to accept build requests.

Lesson 3: Configuring the Rational Build Agent

By default, the Rational Build Agent on the Jazz Team Server checks for build status every 60 seconds. If you want to check status more frequently, you can change this default value.

  1. Use your Web browser to log in to the Jazz Build Server at https://<yourserver>:9443/jazz.
  2. Click Server.
  3. Under Configuration, select Advanced Properties.
  4. Under Build Agent, change the value of the Build Agent Loop Task property from 60 to 10. Rational Build Agent will now poll for build status every 10 seconds.
  5. Click Save.

Lesson 4: Creating data set definitions

A data set definition is a new Jazz model object that is stored in the Rational Team Concert for System z repository. It is a container for information about a data set on the z/OS system. All data sets referenced by a build process must have a corresponding data set definition.

Tip: Optionally, you can use the Rational Team Concert for System z language definitions generator to automate the tasks described in Lessons 4 through 9, instead of using an editor interface to create each one manually. See com.ibm.teamz.manage.doc/topics/c_RTCz_LDGovervu.html for more information about automating the creation of data set definitions, translators, and language definitions.
Create data set definitions for each of the data sets that will be referenced by your build. The following table describes the data set definitions that are required for this tutorial:
Table 2. Required data set definitions
Name Type Allocation Parameters Description
COBOL Destination data set for a zFolder RECFM(F,B) LRECL(80) SPACE(1,1) CYL Data set for COBOL source files
LINK Destination data set for a zFolder RECFM(F,B) LRECL(80) SPACE(1,1) CYL Data set for link-edit source files
OBJ New data set used for build RECFM(F,B) LRECL(80) SPACE(1,1) CYL Data set for object decks
LOAD New data set used for build RECFM(U) LRECL(0) SPACE(1,1) CYL Data set for load modules
TEMPFILE Temporary data set used for build SPACE(5,5) TRACKS UNIT(SYSALLDA) Temporary data sets required by the COBOL compiler
IGYCRCTL Existing data set used for build   COBOL compiler module
IEWBLINK Existing data set used for build   Link-editor module
SCEELKED Existing data set used for build   Data set containing the link-edit stubs for C/C++, PL/I, COBOL, and Fortran languages and Language Environment-provided routines
  1. Create a data set definition that corresponds to the PDSE (partitioned data set extended) that will contain COBOL source code on the build machine.
    1. Expand the Data Set Definitions node in the Team Artifacts view.
    2. Right-click to show the context menu.
    3. Click New Data Set Definition.
    4. Name the data definition COBOL.
  2. In the General section, specify the following parameters:
    • Usage: Destination data set for a zFolder. This specifies that the new data set definition corresponds to a zFolder contained within a zComponent Project.
    • Data set Name: COBOL. This is the name that will be used on your z/OS system after you create this data set.
  3. For data set characteristics, specify the following parameters:
    • Space Units: Cylinders
    • Primary Quantity: 1
    • Secondary Quantity: 1
    • Directory Blocks: 0
    • Record Format: FB
    • Record Length: 80
    • Block Size: 0
  4. Click Save.
  5. Repeat steps 1-4 to create and save a new data set definition named LINK, as described in the table above.
  6. Create a data set definition for OBJ.
  7. In the General section, specify the following parameter:
    • Usage: New data set used for build. This specifies that the new data set definition refers to an output data set that will be used by the build process. In this tutorial, the OBJ data set will be used to hold the object decks produced by the COBOL compiler. If this data set does not exist, it will be allocated during the build.
  8. Select Add data set prefix from build definition to data set name. This indicates that this data set should be prepended with the data set high-level qualifier associated with the build request.
  9. For data set characteristics, specify the following parameters:
    • Space Units: Cylinders
    • Primary Quantity: 1
    • Secondary Quantity: 1
    • Directory Blocks: 0
    • Record Format: FB
    • Record Length: 80
    • Block Size: 0
    • Data Set Type: Library (PDSE)
  10. Create a data set definition for a data set named LOAD, which will store the load module that the build creates.
  11. In the General section, specify the following parameter:
    • Usage: New data set used for build. This specifies that the new data set definition refers to an output data set that will be used by the build. In this tutorial, the LOAD data set will be used to hold the load module produced by the link-editor. If this data set does not exist, it will be allocated during the build process.
  12. Select Add data set prefix from build definition to data set name. This indicates that this data set should be prepended with the high-level qualifier associated with the build request.
  13. For data set characteristics, specify the following parameters:
    • Space Units: Cylinders
    • Primary Quantity: 1
    • Secondary Quantity: 1
    • Directory Blocks: 0
    • Record Format: U
    • Record Length: 0
    • Block Size: 32720
    • Data Set Type: Library (PDSE)
  14. Create a data set definition named TEMPFILE.
  15. In the General section, specify the following parameter:
    • New Temporary data set used for build. This indicates that this data set will be allocated as a temporary file to be used by the build process.
  16. For data set characteristics, specify the following parameters:
    • Generic unit: SYSALLDA
      Tip: For better performance, if you can use VIO (virtual input/output) with your operating system, specify VIO for temporary data sets instead of SYSALLDA.
    • Space units: Tracks
    • Primary quantity: 5
    • Secondary quantity: 5
    • Data set type: Unspecified
    • All other fields: Accept the default values.
  17. Create a data set definition named IGYCRCTL. This data set definition describes the characteristics of the IBM COBOL for z/OS compiler.
  18. In the General section, specify the following parameters:
    • Usage: Existing data set used for build
    • Data set name: The name of the data set that contains the IGYCRCTL module; for example, IGY.V4R1M0.SIGYCOMP.
    • Member: IGYCRCTL
  19. Clear the Add data set prefix from build definition to data set name box.
  20. Create a data set definition named IEWBLINK. This data set definition describes the IEWBLINK module that is used to bind a program and store it in a program library.
  21. In the General section, specify the following parameters:
    • Usage: Existing data set used for build
    • Data set name: Leave blank.
    • Member: IEWBLINK
  22. Clear the Add data set prefix from build definition to data set name box.
  23. Create a data set definition named SCEELKED. This should be the name of the data set on the build machine that contains the COBOL and LE link-edit stubs, generally named CEE.SCEELKED.
  24. In the General section, specify the following parameters:
    • Usage: Existing data set used for build
    • Member: Leave blank.
  25. Clear the Add data set prefix from build definition to data set name box.

Lesson 5 Part 1: Creating translators

Translators are a new Jazz model object that are stored in the Rational Team Concert for System z repository. Translators describe an operation to be performed on a file during a build. A set of translators can be associated with a language definition. During a build, the set of translators associated with a language definition will be reiterated and executed for each file associated with that language definition.

Lesson 5 Part 2: Creating the IGYCRCTL translator

You need the IGYCRCTL translator to compile a COBOL program.

  1. Expand the Language Definitions node in the Team Artifacts view.
  2. Expand the Translators node.
  3. Right-click to display the context menu, then select New Translator.
    1. Name the translator IGYCRCTL.
  4. In the General section, specify the following parameters:
    • Data set definition: IGYCRCTL. This is the data set definition that contains the executable module to be used by this translator. Click Browse to select this data set definition from the list of definitions you created in previous steps.
    • Default options: NODECK,OBJECT,LIB. These options correspond to the PARM parameter field of the JCL EXEC statement.
    • Maximum return code: 0

Lesson 5 Part 3: Configuring the IGYCRCTL DD allocations table

The IGYCRCTL DD allocations table specifies the data set allocations that the module associated with the translator expects to find during a build. In this lesson, specify the following DD allocations for use by the COBOL compiler.

  1. Click Add next to the DD allocations table. Enter the following value:
    • DD name: SYSIN. This is the input COBOL source file.
  2. Select Translator input.
  3. Add a DD Allocation with the following value:
    • DD name: SYSLIN. This allocates the target object module data set.
  4. Select Data set definition for Data set. This indicates that this data set should be allocated using the characteristics specified in the related data set definition.
  5. Click Browse and select the OBJ data set definition.
  6. Select Append member name to data set name. This tells the build process to append the member name of the input data set to the data set name.
  7. Create a DD allocation with the name SYSPRINT, to be used by Antz to collect build output.
  8. Select Data set definition for Data set.
  9. Click Browse to select the TEMPFILE data set definition.
  10. Create DD allocations for the working data sets used by the COBOL compiler during compilation:
    1. Specify SYSUT1 as the DD name.
    2. Select Data set definition for Data set.
    3. Click Browse to select the TEMPFILE data set definition.
    4. Repeat steps a through c to create DD allocations for SYSUT2, SYSUT3, SYSUT4, SYSUT5, SYSUT6, and SYSUT7.

Lesson 6: Creating language definitions

Language definitions are a new Jazz model object that are stored in the Rational Team Concert for System z repository. Each file you build with Rational Team Concert for System z must have a language definition associated with it. For this lesson, you will define language definitions for COBOL compilation and link-editing.

  1. Expand the Language Definitions node in the Team Artifacts view, right-click it to show the context menu, then click New Language Definition.
  2. Specify the following parameters:
    • Name: COBOL
    • Language: COBOL
  3. Click Add next to Translators.
  4. Select Translator and click Browse.
  5. Select the IGYCRCTL translator.
  6. Click OK on the Select a translator panel.
  7. Click OK on the Add a translator panel.
  8. Click Save.
  9. Expand the Language Definitions node in the Team Artifacts view, right-click it to show the context menu, and select New Language Definition. This language definition is for link-editing.
  10. Specify the following parameter:
    • Name: LINKEDIT
  11. Click Add next to Translators.
  12. Select Translator and click Browse.
  13. Select the IEWBLINK translator.
  14. Click OK on the Select a translator panel.
  15. Click OK on the Add a translator panel.
  16. Click Save.

Lesson 7: Creating a shared zComponent project

Now that you have defined your build environment, you must create and share a zComponent project. A zComponent project is a specialized Eclipse project that contains z/OS artifacts–source files, link-edit files, and so forth–and build metadata that are used when you perform builds on a z/OS system. In this lesson, you will create a zComponent project to contain your COBOL source code, and then share the project with your team.

  1. Select Window > Open Perspective > Other.
  2. Select Resource and click OK.
  3. Select File > New > Project.
  4. Select zComponent > zComponent Project and click Next.
  5. Specify your project name and click Finish.
  6. Select your new project in the Project Explorer view, right-click it to show the context menu, then select Team > Share Project.
  7. Select the default component for your workspace and click Finish.

Lesson 8: Adding Rational Team Concert for System z build containers and associating them with data set definitions

A zComponent project is a collection of z/OS data sets. zFolders represent the data sets in your project. Perform the following steps to create the zFolders required for this tutorial.

  1. Expand your project in the Project Explorer view.
  2. Select the zOSsrc folder, right-click it to show the context menu, then click New > zFolder.
  3. Specify COBOL as the zFolder name.
  4. Select the COBOL data set definition. This associates the zFolder with a data set definition. When the Antz build processes this zFolder, the values specified in the data set definition will be used to allocate the corresponding zFolder z/OS data set.
  5. Click Finish.
  6. Follow steps 1 through 5 to create a LINK zFolder and associate it with the LINK data set definition.

Lesson 9: Adding Rational Team Concert for System z build artifacts and associating them with language definitions

You are now ready to define the artifacts your new project requires. You will create a COBOL source file, and then a file that contains the bind instructions for the link-editor. You will also associate these resources with language definitions.

  1. Select the COBOL folder, right-click it to show the context menu, then click New > zFolder.
  2. Specify HELLO.cbl as the zFile name.
  3. Select the COBOL language definition.
  4. Click Finish.
  5. Double-click HELLO.cbl.
  6. Enter the following in the source editor and click File > Save. You can cut and paste from the following example.
    Important: The first character should start on the 8th column.
           IDENTIFICATION DIVISION.
           PROGRAM-ID. HELLO.
           PROCEDURE DIVISION.
           MAIN.
               DISPLAY 'Hello, world.'.
               STOP RUN.
  7. Select the LINK folder, right-click it to show the context menu, then select New > zFile.
  8. Specify HELLO.lnk as the zFile name.
  9. Select the LINKEDIT language definition.
  10. Click Finish.
  11. Double-click HELLO.lnk.
  12. Enter the following in the source editor and click File > Save. You can cut and paste from the following example.
    Important: The first character should start on the 2nd column.
    INCLUDE SYSLIB(HELLO)
    NAME HELLO(R)
  13. Switch to the Work Items perspective.
  14. Open the Pending Changes view.
  15. Check in and deliver all changes.

Lesson 10 Part 1: Creating a new build definition

Rational Team Concert for System z provides a new build definition template called Antz – Rational Build Agent. Use this template to define an Ant-based build to use on Rational Team Concert for System z using the Rational Build Agent.

  1. In the Team Artifacts view, right-click the Builds node and select New Build Definition.
  2. Click Next to create a new build.
  3. Specify a Build Definition ID and select the Antz - Rational Build Agent template.
  4. Click Next.
  5. Select Jazz Source Control - zOS. This specifies that you want to use the Rational Team Concert for System z file agent to extract the files from the repository and place them on the target build system.
  6. Click Next.
  7. Select Job Output Publishing. This enables translator output reporting, such as SYSPRINT, for this build definition.
  8. Click Finish.

Lesson 10 Part 2: Using the build definition editor

In the build definition editor, perform the following steps to configure your build definition:

  1. On the Overview tab, select RationalBuildAgent for the Supported Build Engines value.
  2. Make sure that the Build Agent tab contains the following values:
    • Hostname: Your build machine IP address or hostname
    • Port: 5555 or the port number you configured in your bfagent.conf file
    • User name: The z/OS RACF user ID of the builder on the target build machine
    • Password and Confirm Password: The builder's z/OS RACF password
  3. After you have configured the Build Agent tab, click Test Connection to test the connection to your build agent. If the connection was successful, you should see results that are similar to these:
    Message: Socket created successfully.
    Authentication Pass.
    
    Platform: os/390 19.00 03
    Version: 7.1.2.0-0-0003
    PingResult: PingOk
    ExitStatus: 0
  4. On the Job Output Publishing tab, make sure that you select Publish job output logs.
  5. On Jazz Source Control - zOS, set the following values:
    Build Workspace
    Click Select to select the repository workspace to be built.
    Load directory
    Specify an absolute path in USS to use to store non-MVS build artifacts such as the Antz build.xml file. The builder user ID must have read, write, and execute permissions on this directory.
    Data set prefix
    Specify the prefix to be prepended to managed data sets. For example, if you specified BUILDER.TEST as the data set prefix, the data set BUILDER.TEST.COBOL will be allocated for the COBOL zFolder associated with the COBOL data set definition in previous steps.
  6. Set the Build File field on the Antz tab to the absolute USS path of the Antz build file. If you want to use the build.xml file in the zComponent project you already created, the file path should be <load directory>/<project directory>/build.xml. If you named the zComponent project DEMO, the path to the build file could be ${teamz.scm.fetchDestination}/DEMO/build.xml.
    Note: ${teamz.scm.fetchDestination} is a property whose value points to the directory you specified in the Load directory field of the Jazz Source Control - zOS tab.
  7. Click Save.

Lesson 11: Requesting a build

You have now successfully defined all of the steps needed to complete this tutorial. To request a build, perform the following steps:

  1. In the Team Artifacts view, select your build definition, right-click it to show the context menu, then select Request Build.
  2. Click Submit on the Request Build panel.
  3. If a warning is displayed that states that the build engine does not seem to be processing requests, click OK to submit the request.
  4. In the Builds view, be sure you periodically check the status of your build. Click Update to refresh the status view.
  5. When the build is complete, double-click the build result.
  6. Go to the Logs tab and double-click the log file. The Logs tab should contain the following files:
    • Two SYSPRINT.log files: One file contains the output from the COBOL compiler; the other contains the output from the link-editor.
    • build-XXXXXXXXXXXXXX.log. This file contains the Rational Build Agent build log.
  7. Look at the last lines of the Rational Build Agent log. If you see a Status:OK message, you have successfully completed this tutorial.
  8. The Downloads tab of the build results should contain the following files:
    build.properties
    A properties file that contains all properties and their values used to perform this Antz build.
    buildableFiles.xml
    An XML file that contains information about each file that the Antz build processed. Only those files associated with a language definition are included in this list.
    FAOperationList.xml
    An XML file that contains operations that were requested of the File Agent during this build.
    fetchedFiles.xml
    An XML file that contains information about each file that was extracted from the repository by the file agent during this build.
    macrodefs.xml
    An XML file that contains Ant macros that were generated for use by this build. The contents of these macros are created based on values you specified in the language definitions associated with the files processed by this build.