Installing and configuring the DBB toolkit on z/OS

Installing

The Program Directory for IBM Dependency Based Build contains the information about the material and procedures to install the Dependency Based Build toolkit. To download a PDF version of the program directory, click here.

The results of the SMP/E installation are a USS directory found at /usr/lpp/IBM/dbb and a data set containing sample members that were used for the installation. The USS directory contains the following sub-directories:

Environment variables

Beginning in DBB V1.0.2, several Dependency Based Build toolkit APIs will require the existence of two environment variables in order to function correctly. These variables can be configured by using the dbbenv.sh file.

Configuring and customizing

The configuration of the DBB toolkit requires the creation of build scripts to be executed by build users or via automation such as Jenkins. The following information is provided as reference when you need to customize DBB.

There are several files in the installation conf sub-directory that may need to be modified or copied to other directories to enable DBB functions in certain circumstances. As you implement build scripts and use these functions, it may become necessary to customize these files and reference them from a directory outside of the SMP/E installation, such as /etc/dbb. These files are as follows:

• gitenv.sh: Sets Git environment variables, which might be needed from either a user terminal session or during a Jenkins build invocation. The gitenv.sh shell script is in the DBB toolkit installation (<dbbToolkitInstall>/conf/gitenv.sh) and is pre-populated with the variables defined in the Rocket® Git client README.ZOS for customization. For more information, see Setting up Jenkins sample application.

• rse-dbb.env: Provides environment variable entries to IBM Developer for z/OS. To configure this file, do the following steps. For more information, see Integrating with IDz.

  1. Locate the z/OS Explorer Extensions configuration directory. The default is /etc/zexpl.
  2. Copy rse-dbb.env to this directory. Review the comments and directories in the file to insure they are correct for your environment.
  3. Restart the z/OS Explorer Extensions RSE daemon. The default name for this started task is RSED.

Note：Starting from DBB V1.0.6 and IDz V14.2.0, idzdbb.env is renamed to rse-dbb.env.

• log4j2.properties: Configures how to gather DBB debug information. A sample file is provided in /usr/lpp/IBM/dbb/conf and you can copy it to your directory.

  By default, if a log4j2.properties file is found in the classpath, the settings contained in that file is used. To override the default, you can specify a log4j2.properties file on the command line when you run the build script, e.g. groovyz -Dlog4j.configurationFile=file:/your_dir/log4j2.properties build.groovy.

  Configure log4j2.properties to gather DBB debug information as follows. For standard log levels built into Log4J, see https://logging.apache.org/log4j/2.x/manual/customloglevels.html.

  • Option 1 (Recommended): Set a logging level lower than DEBUG and set what to trace for DBB

    In the sample log4j2.properties file, the logging level is set to WARN, which is adequate for most cases, and DBB tracing options are listed but marked as comment. To enable tracing with a non-debug logging level, for example, rootLogger.level=WARN, you must uncomment the corresponding lines according to your need. For example, you can enable all tracing options for DBB as follows:

    # Uncomment to enable tracing for build commands
    logger.build.name=com.ibm.dbb.build
    logger.build.level=DEBUG
    logger.buildInternal.name=com.ibm.dbb.build.internal
    logger.buildInternal.level=DEBUG
    
    # Uncomment to enable tracing for dependency scanning and resolution
    logger.dependency.name=com.ibm.dbb.dependency
    logger.dependency.level==DEBUG
    logger.dependencyInternal.name=com.ibm.dbb.dependency.internal
    logger.dependencyInternal.level=DEBUG
    
    # Uncomment to enable tracing for build report generation
    logger.buildReport.name=com.ibm.dbb.build.report
    logger.buildReport.level=DEBUG
    logger.buildRecords.name=com.ibm.dbb.build.report.records
    logger.buildRecords.level=DEBUG
    
    # Uncomment to enable tracing for repository connection
    logger.repository.name=com.ibm.dbb.repository
    logger.repository.level=DEBUG
    logger.repositoryInternal.name=com.ibm.dbb.repository.internal
    logger.repositoryInternal.level=DEBUG
    

  • Option 2: Set the logging level to DEBUG or higher

    Note that with rootLogger.level=DEBUG or a higher logging level, you get debug information from the entire application rather than from the designated packages, which might be overwhelming and make it difficult to spot the needed trace statements.

• runIspf.sh: Invokes ISPZXML. DBB executes TSO and ISPF commands through the Legacy ISPF Gateway XML API (ISPZXML) provided by ISPF. The runIspf.sh script sets up the environment to call ISPZXML and passes the XML input to ISPZXML. It may be necessary to customize this script for your environment. For more details, see z/OS command API.

• dbbenv.sh: Exports two environment variables: DBB_HOME and DBB_CONF. These are set by default as /usr/lpp/IBM/dbb and /usr/lpp/IBM/dbb/conf. Ensure these values match your installation.

DBB daemon files

The following files are for the DBB daemon. For more information about the DBB daemon, see Improving performance with ZD&T or Java startup by using DBB daemon. Ignore these files if you do not want to use the DBB daemon.

• process_definitions.xml: This file defines the processes that the daemon maintain in the background. The following table shows the process definition options that you can set in the file.

For the most part, no changes are needed unless your directories are different than above. The value for Delay is best set at the time it takes to run a build. The value for Count depends on how many builds you are running using the daemon.

Example of a process definition

<ProcessDefinition>
    <name>groovyz</name>
    <process>com.ibm.dbb.build.ext.buildprocess.GroovyBuildProcess</process>
    <classpath>/usr/lpp/IBM/dbb/lib/*:/usr/lpp/IBM/dbb/groovy-2.4.12/lib/*</classpath>
    <options>-Djava.library.path=/usr/lpp/IBM/dbb/lib/</options>
    <count>1</count>
</ProcessDefinition>

• DBBS.jcl: In order to use the shared daemon, set the value of CNFG in line 34 to the location of startdaemon.sh.
• startdaemon.sh: You must edit this startup script as follows to use the shared daemon:
  1. Update JAVA_HOME to match your environment variable.
  2. Update DBB_DIRECTORY to match your installation directory.
  3. If you want to use a different HOSTNAME or PORT, update these values. Hostnames must be IP addresses.
  4. Update PD_FILE if you have moved process_definitions.xml to another location.
• BGZDBBP.jcl: In order to use the personal daemon, set the value of CNFG in line 34 to the location of personaldaemon.sh.
• personaldaemon.sh: You must edit this startup script as follows to use the personal daemon:
  1. Update JAVA_HOME to match your environment variable.
  2. Update DBB_HOME to match your installation directory.
  3. Update PD_FILE if you have moved process_definitions.xml to another location.
  4. Update timeout option if you want the personal daemon to time out.

Enabling System Management Facility (SMF) support

For more information about SMF support in DBB and its enabling and configuration, see System Management Facility (SMF) support.