Specifying z/OS dependency build settings

You can modify the settings for the operating system after you create a build definition by using the Build Definition editor.

1. In the Team Artifacts view, expand the project folder.
2. Expand the Builds node, right-click your build definition, and click Open Build Definition.
3. In the Build Definition editor, click the Overview tab.
   1. Optional: In the General Information section, briefly describe your build definition in the Description field.
   2. Select the Ignore warnings when computing overall status check box.
   3. In the Supporting Build Engines field, click Create to create a build engine, Add to add one, or Remove to remove one.
      Note: Dependency builds require a Rational® Build Agent build engine.
   4. Optional: In the Pruning Policy section, select the Prune build results checkbox, and then type the number of successful and failed builds to save.
4. Optional: Set up automatic builds on the Schedule tab.
   1. Select the Enabled checkbox; then, add or remove automatic builds as needed.
   2. In the Build time section, click either Continuous interval in minutes and then indicate that interval; or click and specify the time in which to run the build.
   3. In the Build days section, select the days to run the build on.
5. To add, edit, or remove build definition properties, use the Properties tab.
6. Optional: Click the Output Publishing tab, and then select the Publish job output logs check box, so that the information that compilers generate are attached to the build results. You can also select Publish only when an error occurred to reduce the attached job output logs, and select Publish successful logs as .zip files (one .zip file per 100 logs) to compress the logs into a single file.
   Logs are published to the build results in batches. You can configure the batch size on the Output Publishing tab of the build definition editor. In the Number of logs to publish at a time field, select how large the batch size should be before publishing the logs. The default batch size is 10.
7. Click the Jazz Source Control tab. In the Build Workspace section, either select a workspace or create one.
   Note: Specify a dedicated build workspace for your build definition. For more information, see Dedicated build workspaces. Set the visibility of the build repository workspace so that the Jazz® user you configured for your Rational Build Agent can access the workspace in read-only mode.
   1. In the Load Options section, specify file extraction details, such as a load directory and a resource prefix.
      Note: It is advised to avoid using blanks or $ in the path or the prefix as these characters (or their national language equivalents) can cause inconsistent results.

      You can reference properties by using this format in your build script: ${propertyName}.

   2. Select one or more load options.

      The following options apply to Multiple Virtual Storage (MVS™):

      • Load workspace to the resource with the resource prefix at the beginning of the build. Select this option to specify whether artifacts that are stored in an enterprise file system (like a PDSE) are loaded to the resource with the designated resource prefix at the beginning of a build. If you do not select this option, artifacts are loaded during the build as necessary. Reference this option in the build script with this property: team.enterprise.build.ant.fetchAll.
      • Select components to always load during dependency build. Instead of loading everything in the workspace, you can scope the load to specific components. If this list contains one or more components, only the artifacts in these components are loaded to MVS sandbox. If this list is empty, all artifacts in the workspace are loaded to MVS sandbox. You are recommended to specify always load components instead of using always load at the file level.
      • Select Log Loading to create a log file and attach it to the build results on the Logs tab. The log file shows all of the commands that run to perform the required loading.

      These options apply to the z/OS® UNIX file system:

      • Select the Delete directory before loading check box to delete the metadata for the load directory.
        Tip: Metadata stores information about the files you load from Engineering Workflow Management. When a build fails because of corrupted metadata, select the Delete directory before loading check box to clean up the metadata and resolve the issue. However, when metadata is not corrupted and you select this option, your build might take longer to complete. Select this option only if you want to clean up the load directory and associated metadata.
      • Load workspace to the load directory at the beginning of the build. Select this option to specify whether artifacts stored in the z/OS UNIX file system are loaded to the directory at the beginning of a build. Reference this option in the build script with this property: team.enterprise.build.ant.fetchWorkspaceBeforeBuild.
        Important: If you do not select this option, no file is loaded to the z/OS UNIX file system.
      • Create folders for components. Reference this option in the build script with this property: team.enterprise.scm.createFoldersForComponents.
      • In the Components to exclude field, be sure to select which components to exclude if you are loading only some of them. Reference this option in the build script with this property: team.enterprise.scm.loadComponents.
      • In the Load rules field, select which load rules you want to use to describe how to load the build workspace. Reference this option in the build script with this property: team.enterprise.scm.componentLoadRules.
   3. In the Accept Options section, select one or more options.
8. If you chose the command-line build option when you created the build definition, specify the configuration details for the command-line build on the Pre-Build Command Line tab. These properties include commands, a working directory, and a connection timeout. Reference properties by using this format: ${propertyName}.
9. Click the z/OS Dependency Build tab, and then click the General tab.
   1. In the Build File and Targets section, click Generate a build file from these language definitions to automatically generate a build file from the available language definitions. The order of the language definitions determines the sequence in which items are built.
      Notes:

      • If you are not sure of the order that you want to set the language definitions, you can open any of the language definitions in the list by double-clicking the name of the language definition.
      • If you click Generate a build file from these language definitions, the language definition you specify must have a translator that is associated with it, or a build file cannot be generated. If you do not have language definitions in this project area that are associated with translators, browse to another project area.
      The generated build file, generatedBuild.xml, is attached to the build results on the Downloads tab.
   2. Optional: Instead of generating a build file, you can specify a custom build file and build targets by clicking Use an existing build file.
   3. Optional: Select the Trust build outputs check box.
      • When you select this check box, the build runs on the premise that you did not delete or modify the outputs that were created in previous builds. This option improves performance when you rebuild because you skip unnecessary checks for missing or changed outputs.
      • When you select this check box, even if you delete outputs (like program objects) on the build server, Ant does not initialize, and nothing is built unless you made associated changes in the repository, such as changes in the source code.
   4. Optional: If you want to automatically delete obsolete output files that are no longer produced by buildable files, select the Delete obsolete outputs check box.
      This option saves space and prevents your build system from storing unnecessary files.
   5. Optional: If you want to publish build map links to the External Links tab, select the Publish build map links check box.
   6. Optional: If you have translators that use a call method of TSO/ISPF command or EXEC, and you want ISPF to reuse the ISPF session, select the Reuse ISPF Session check box.

      Using this option can bring performance benefits. However, if you have selected a number greater than 1 in the Number of sub-processes used to run a build option, then you must not select the Reuse ISPF Session check box because doing so will bring inconsistent results. The ISPF Gateway does not support reusable ISPF sessions in a multi-threaded use case.

      Note: Select the Reuse ISPF Session check box for advanced use cases only.
   7. Optional: If you want to start an HFS build, select the Enable HFS builds check box. Then specify the HFS outputs directory.
   8. Optional: In the Frequency of updates to the number of buildable files preprocessed in the build report contribution summary field, define the number of files to preprocess before updates are made in the Build Result editor.
   9. Optional: In the BPXWDYN Options field, define any options that you want to pass to the BPXWDYN interface, which you use to allocate data sets. The default value is MSG(1), which means that messages are directed to file descriptor 1, which is the build log file for all Ant with Enterprise Extensions and dependency builds.
   10. Optional: In the Pre-build script and Post-build script fields, specify a script to run before and after the build script runs.
   11. Optional: To run the script even if one or more errors occur when your build script runs, select Always run post-build script check box.
10. In the Ant with Enterprise Extensions Configuration section, specify any configuration details, including the following options:
    • Ant home
    • Ant arguments. The default is -verbose.
    • Working directory
    • Java™ home
    • Java VM arguments. The default is -Xquickstart.
    • Properties file
11. To enable dependency builds, select the Dependency Options tab, and then click either Build workspace or, to limit builds to a subset of the buildable items, click Build subset.
    If there are files to be included in each build for this build definition, select Mandatory subset. Click Browse to locate the subset containing the files that are required to be included in this build. The files in the mandatory subset are always built, even if they are not changed.
12. Optional: Select any of the following options for your builds:
    1. The Build changed items only is selected by default. If you clear that option, all items are built unless they are excluded.
    2. Near the Select components to be excluded from build field, click Select to add components that you do not want to be processed in the build.
       By selecting this option, you can improve build performance by reducing the number of files that are processed during a dependency build.
    3. Expand the Impact calculations (advanced) section to limit which calculations are included during build preprocessing. The build processing feature normally runs various queries to find files that are affected by the changed files. All of the queries are selected by default, but you can clear the impact calculation check boxes to disable the queries.
    4. In the Advanced section, select Conditional build to specify that you want to cancel a build request if an error occurs.
       Also in the Advanced section, for the Number of sub-processes used to run a build option, you can specify the number of processes to use in z/OS dependency builds. Dependency builds support using multiple processes for compilation activities. As an alternative, you can specify the team.enterprise.build.dependency.ProcessCount build property on the Properties tab.

       Note: If ISPF Gateway processes are to be used when multiple processes are run for compilation activities, go to Configuring the ISPF gateway for build, deployment, and promotion support to discuss setting up ISPTLIB to avoid enqueue issues.
13. Optional: Click the Request Options tab to set the options that are to be available on the Request Build dialog. The options you select are enabled in the request, and the options that are not selected are hidden. The following options are new on the Request Build dialog.
    • Mandatory subset, if the build is a workspace build and Build changed items only is not selected
    • The Advanced options section contains some properties from the build definition that were not previously on the Request Build dialog.

    Restrictions:

    • Personal Build Options are only shown on the Request Build dialog if Personal Build is selected.
    • The options for editing the build file and build targets are only displayed if you are not generating a build file.
    • The Pre-build script option is only displayed if the build definition has a pre-build script.
    • The Post-build script option and the Always run post-build script option are only displayed on the Request Build dialog if the build definition has a post-build script. When the Post-build script option is not selected, the Always run post-build script option is hidden.
    • If the Pre-build script or Post-build script options are not selected, the corresponding property is hidden so that the script is not processed.
    • If the requestor lacks permission under the Enterprise Build permissions and does not have JazzAdmin capabilities, the Advanced options are hidden on the Request Build dialog .

    The Build workspace, Build subset, and Personal build options can not be hidden on the Request Build dialog. The Repository workspace, Load directory, and Resource prefix options can not be hidden for personal builds.
14. To use the Interactive ISPF Gateway to build your translators that use ISPF or TSO commands, click the Interactive Gateway tab.
    • Select the Enabled checkbox.
      Note: When the Enabled checkbox is cleared, your ISPF/TSO translators use the legacy gateway.
    • Specify the Interactive ISPF gateway parameters; these are the same items that are entered when a user logs on to a TSO/E session:

      Procedure name

      The name of the TSO/E logon procedure to be used for a TSO/E session. This parameter is required on a request for the start of a new TSO/E session. Valid values are 1 to 8 characters long.

      Account number

      The TSO/E account number to be used for a TSO/E session. This parameter is required on a request for the start of a new TSO/E session. Valid values are 1 to 40 characters long.

      Group name

      The TSO/E group name to be used for a TSO/E session. This parameter is required on a request for the start of a new TSO/E session. Valid values are 1 to 8 characters long.

      Region size

      The region size to be used for a TSO/E session. This parameter is required on a request for the start of a new TSO/E session. Valid values are 0 to 2,096,128.

    • Optional: Specify STEPLIB.

      As described in TSO/ISPF client gateway, if the modules that are required by the Interactive ISPF Gateway are not in the LINKLIST, they should be specified through STEPLIB.

15. Click Save.