Configuring the Rational Build Agent shell script

The Jazz® Build System contains a sample script named that you can use to start the Rational® Build Agent.

You can find the sample script in the @pathPrefix@/usr/lpp/jazz/v7.0.1/buildsystem/buildtoolkit/examples/startbfa directory, where @pathPrefix@ is any prefix you specify when you install the SMP/E. This script is required to start the Rational Build Agent to specify credentials so that the agent can connect to the Jazz Team Server, and to provide you with access to libraries you need for Ant with Enterprise Extensions and native compilation. This script is copied to the IBM® Engineering Workflow Management (EWM) configuration directory, typically /etc/jazz701/ccm by the BLZCPBTK job.
Important: The script must be configured to suit your environment. Many of the variables required will have been configured by the BLZCPBTK copy and configuration job. However, some of the variables, such as user ID and password information will not be set automatically. Review and replace the required 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, and then /usr/lpp.
@javaPathPrefix@ Directory path to the IBM 64-bit SDK for z/OS® Java™ 2 Technology.
@yourUserid@ The Jazz user ID.
@yourPasswordFile@ The Jazz password file as defined by the BLZBPASS job. See Running the Jazz Build Engine on z/OS for information about how to run the BLZBPASS job.
@stepLib@ The STEPLIB DD (data set definition) to use in your z/OS build. For example, BLZ.SBLZLOAD
@bfaBinPath@ Directory path to the Rational Build Agent executable directory.
@bfaConfPath@ Directory path to the Rational Build Agent configuration file directory.
@zLang@ Encoding used in host files. For example, IBM-037.
@timeout@ Timeout value in seconds for build step execution. Default if not specified is 300 seconds.
@workPath@ Directory path where metadata are stored for PDSEs. By default this is /u/jazz701/ccm/.
@yourHomeDirectory@ Your home directory. Use this only when you have not defined the HOME environment variable somewhere else.
_CMDSERV_BASE_HOME Indicates the location of the ISPF-supplied files so the Rational Build Agent can start the ISPF gateway. See Configuring the ISPF gateway for build, deployment, and promotion support for more information about _CMDSERV_BASE_HOME.
_TEMPORARY_UNIT The temporary unit, for example SYSALLDA, to use the DASD unit of your choice for the allocation of temporary data sets. It does not override the unit specified in the data set definitions. It is used for internal work data sets in EWM processes that run on z/OS, for example in the ISPF client.
VIO_UNIT The unit required for VIO in the build, if VIO is not supported or has a different name. For example, set VIO_UNIT to SYSALLDA to use DASD for VIO. It can also be specified in the build engine or as a build property in the build definition.
When you are ready to start the Rational Build Agent and accept build requests you can run the script one of the following ways:
  • Start the script manually from OMVS
  • Configure the sample started task BLZBFA supplied in the BLZ.SBLZSAMP library by following the instructions in the job. You will then be able to run the Build Forge Agent as a started task at system startup. You must copy this job to a system allocated PROCLIB and set up required security settings in order for it to run as a started task.
Important: In an environment with multiple TCP/IP stacks, add:
export _BPXK_SETIBMOPT_TRANSPORT=tcp_stack_name
to the shell script, which uses the USS _BPXK_SETIBMOPT_TRANSPORT variable to specify the name of the TCP/IP stack used.
  • Unless another shell is specified in your bfagent.conf file, the default shell (/bin/sh) is used in the session started by the Rational Build Agent on z/OS.  The default shell on z/OS always runs the /etc/profile script for setting system-wide configurations after the runs and it is possible that some environment variables set in the shell script can be overridden.
  • When you run an Ant with Enterprise Extensions build or dependency build with either the –verbose or –debug option in the Ant arguments, the UNIX export command runs before Ant is invoked. You can look at the outputs from the export command in the build log to make sure the environment variables are correctly set.
  • If you need to specify other environment variables to control how the build agent runs, you can either add UNIX export commands to the script, or ensure that the environment variables are previously set for the user environment where the build runs.
  • If some environment variables are overridden by /etc/profile, ask your system programmer to change /etc/profile. If it is not possible to change /etc/profile, you can use the bash shell, which is available with the Rocket Software tools. Specify the –noprofile option by adding following two lines to your bfagent.conf file:
    shell /bin/bash   
    shellflag --noprofile 
  • If build agent logging is enabled in bfagent.conf through the activity_log property, the Build Agent shell script will, by default, archive the current log when the agent is started. By default, 5 previous logs will be kept, but this can be changed by altering the NUM_LOGS variable.