Improving z/OS dependency build performance

You can improve the performance of the z/OS® dependency builds that you run on IBM Z® Systems Development and Test Environment (ZD&T). For this purpose, Engineering Workflow Management (EWM) Enterprise Extensions (EE) provides an optional mechanism that is based on the Build Manager tool of the IBM® Dependency Based Build product.

Before you begin

Installation:
  • In addition to the standard configuration for z/OS dependency builds, the Build Manager requires the SMP/E installation of the IBM Dependency Based Build FMID (HBGZ100). This FMID is packaged with the Engineering Lifecycle Management (ELM) 7.0 SMP/E package.
Configuration:
  • The EWM EE configuration tool and the BLZCPBTK sample have been updated to copy and configure the startdaemon.sh and client.sh files from the product installation directory to the user configuration directory /etc/jazz700/ccm/pvm by default.
  • The Rational® Build Agent startbfa.sh has an optional property setting: team.enterprise.clientPath can be used to override the default location.
  • A new started task sample, BLZPVM, is added for starting the daemon. RACF® STDATA can be associated with this started task to control which user ID is to be used for dependency builds.
  • The number of client processes is set in the initial setup, but can also be changed later by editing the startdaemon.sh script. You can change the COUNT variable to change the number of Java™ virtual machine (JVM) processes that are started by the daemon.
    • A delay property (in seconds) is also set in the initial setup. It can also be changed later by editing the DELAY property in the startdaemon.sh script.
    • If a process is unavailable (busy working on another build), the Build Manager waits for a specified amount of time (DELAY) to try one more time. If it is still busy on the second attempt, the build fails.
      Example: COUNT is set to 1 and DELAY is set to 1 second. You run two consecutive builds (build A and build B). Build A gets run first. Build B sees that the 1 process is busy and waits 1 second to try again. After this 1 second, if the process is still busy, build B fails.
Restrictions for EWM EE z/OS dependency based builds that use the Build Manager:
  • The build request cannot use build agent overrides to run the build process under a different user ID.
  • This capability is limited to ZD&T use.
  • This capability is limited to z/OS dependency builds.
  • The user ID that starts the daemon must have full permissions to any destination that a build might request.
    Example: There are two users: user A and user B. User A has permissions to the /u/A/* directory only and user B has permissions to all the /u/* directories. User A starts the daemon. Then, user B requests a build that builds to /u/B/test. The build fails because the daemon is running under user A’s permissions. Therefore, for this to work, user B or a shared function build user needs to start the daemon.

About this task

The IBM Dependency Based Build product and its Build Manager are documented in the IBM Knowledge Center. For more information, see Dependency Based Build (DBB).

The Build Manager maintains multiple long-running, persistent Java processes to avoid Java virtual machine (JVM) startup when running builds and to optimize the overall build time. EWM EE can be configured to use the Build Manager.

The Build Manager has two components: the socket server daemon for managing and maintaining processes and the socket client for entering build commands.

Procedure

  1. Start the Build Manager daemon and associated client processes by using one of the following methods:
    • Use the started task JCL BLZPVM that is provided by EWM (suggested approach).
    • Start the daemon in a shell environment by starting the startdaemon.sh script, which is located by default in /etc/ccm/pvm/startdaemon.sh.
  2. Configure the build agent settings through two properties that are used to run builds with the Build Manager:
    • Set the team.enterprise.useBuildManager property to true to use the Persistent JVM. It uses the following default path for the client.sh script: /etc/jazz700/ccm/pvm/client.sh.
    • Optionally set the team.enterprise.clientPath property to override the default path to client.sh.
    Note: You can also set these two properties when you set up the build definition. See the next step for details.
  3. Set up the build definition by following the standard steps to create a z/OS dependency based build. All the steps are explained in Specifying z/OS dependency build settings.
    Note: If you did not configure the build agent settings, you can set the team.enterprise.useBuildManager and team.enterprise.clientPath properties in the Properties tab of the build definition.
  4. Run a build on the Build Manager.
    1. Make sure that you have set the property team.enterprise.useBuildManager and, if applicable, the optional property team.enterprise.clientPath.
    2. Submit a build. Your build will use the Build Manager.
  5. Verify that the build used the Build Manager.
    1. Open the build log.
    2. Search for using_pjvm.

      You should find a line like SCRIPT /bin/sh /etc/jazz700/ccm/pvm/client.sh. In this line, you should see that client.sh is called rather than java.

      If you cannot see such a line and, instead, find a line like SCRIPT /usr/lpp/java/J8.0_64/bin/java, then the build did not use the Build Manager.

  6. Stop the daemon and associated client processes by using one of the following methods:
    • If you started the daemon with the JCL job BLZPVM, you can kill this job to stop the daemon.

      If you go into SDSF, you can see that multiple jobs related to the Build Manager are running. They are all prefixed by BLZPVM. You need to cancel all the BLZPVM* jobs to successfully stop the Build Manager.

    • If you started the daemon in the shell environment, you can stop it by finding the related PIDs.
      Example: Screen that displays the list of the PIDs that are related to the daemon
      • Find a process that starts with var/dbb100FIX/usr/lpp/IBM/lib/server. In the example, it is PID 83886134.
      • Find a process that starts with sh -c /usr/lpp/java/J8.0_64/bin/java -classpath. There is one process for each JVM that you started. In the example, it corresponds to PIDs 67109000 and 79.
      • To stop the daemon in this example, you must enter the following command:
        kill -9 67109000 79 83886134

Results

The Build Manager might send error messages about failed builds. Two common messages are explained below, with their possible causes and the solutions to fix them.
  • WARNING: No processes of that type are available

    This warning can also be followed by the following message:

    Build Manager Daemon Might Not be Started or Suffered an Internal Error.

    It means that you are requesting multiple builds from the daemon at one time. If one build is running on the daemon and another build tries to request the process, it fails. If the process is busy, a build tries once, waits for the specified DELAY time, and tries a second time. If it fails the second time, then the build fails.

    You can fix this warning in the following ways:
    • You can specify a higher number for the DELAY, which is the number of seconds that the build waits in between retrying a busy process. Then, it can ensure that a busy process is finished before retrying a build request. You can specify the amount of time that a build normally takes.
    • You can specify a higher number for the COUNT, which is the number of JVM processes to run. Then, more JVM processes are available to run builds on.
  • ERROR: Failed to connect to port

    This error can also be followed by the following message:

    Build Manager Daemon Might Not be Started or Suffered an Internal Error

    If you see this message and no other stack trace along with it, then most likely your Build Manager Daemon is not running.

    You can fix the error by restarting your Build Manager. See the explanations for stopping (step 6) and starting (step 1) the Build Manager.


video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki