Contribute in GitHub:

Installing and configuring the DBB toolkit on z/OS

Installing

The Program Directory for IBM Dependency Based Build contains the information about the materials 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 subdirectories:

Subdirectory	Usage
archive	Supporting product archives including Db2 activation `.zip` file
bin	Executable scripts
conf	Configuration files to be modified by the user
groovy	Groovy distribution
lib	DBB API jar files
migration	Sample scripts related to migration

Environment variables

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

Name	Description
DBB_HOME	DBB home directory
DBB_CONF	DBB configuration directory

Java environment variables for a proxy fronted DBB web application

In certain situations, you might have to restrict access to the DBB web application. For example, the DBB web application might be accessible only through a front-end proxy server. For this topology, you must use the following Java™ environment variables when invoking a Groovy scripting file that requires communication to the protected web application. These Java Networking settings are explained in Java Networking and Proxies in the Oracle documentation.

You must set the following properties for the protocol handler:

Name	Description
-Djava.net.useSystemProxies	Set to `true`
-Dhttps.proxyHost	IP address or hostname of the proxy host
-Dhttps.proxyPort	Port number of the proxy host

The following code is an example of how to invoke a Groovy script where the web application is accessed through a proxy server.

groovyz -Djava.net.useSystemProxies=true -Dhttps.proxyHost=123.12.1.1 -Dhttps.proxyPort=50050 build.groovy

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.

Several files in the installation conf subdirectory might 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 might 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 ensure 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. Indicate 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. It 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.

Value	Definition
Name	The alias that you use when referring to the process with the client
Process	The Build Process that is used for this process (no change is needed)
Classpath	The classpath for the process launched (change it depending on your installation)
Options	Any options that you want to pass to the Build Process (such as debug)
Count	(Optional) The number of processes that you want to preload (If count is greater than 0, the personal daemon will only pre-start 1 process. You can start additional processes manually.)
Delay	(Optional) The delay time to retry a process if all current processes are busy

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 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 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.