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. Thegitenv.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 clientREADME.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.- Locate the z/OS Explorer Extensions configuration directory. The default is
/etc/zexpl
. - Copy
rse-dbb.env
to this directory. Review the comments and directories in the file to ensure they are correct for your environment. - Restart the z/OS Explorer Extensions RSE daemon. The default name for this started task is RSED.
- Locate the z/OS Explorer Extensions configuration directory. The default is
Note:Starting from DBB V1.0.6 and IDz V14.2.0,
idzdbb.env
is renamed torse-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 alog4j2.properties
file on the command line when you run the build script. Indicategroovyz -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. TherunIspf.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
andDBB_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 ofCNFG
to the location ofstartdaemon.sh
.startdaemon.sh
: You must edit this startup script as follows to use the shared daemon:- Update
JAVA_HOME
to match your environment variable. - Update
DBB_DIRECTORY
to match your installation directory. - If you want to use a different
HOSTNAME
orPORT
, update these values. Hostnames must be IP addresses. - Update
PD_FILE
if you have movedprocess_definitions.xml
to another location.
- Update
BGZDBBP.jcl
: In order to use the personal daemon, set the value ofCNFG
to the location ofpersonaldaemon.sh
.personaldaemon.sh
: You must edit this startup script as follows to use the personal daemon:- Update
JAVA_HOME
to match your environment variable. - Update
DBB_HOME
to match your installation directory. - Update
PD_FILE
if you have movedprocess_definitions.xml
to another location. - Update timeout option if you want the personal daemon to time out.
- Update
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.