The shared daemon

Note: The current documentation of the shared daemon is valid only for DBB 2.0.2 and later. If you are using DBB 2.0.1 or earlier, refer to the DBB 2.0.1 PDF or the DBB 2.0.0 PDF for the shared daemon documentation.

Starting from DBB 2.0.2, the shared daemon configuration includes additional security mechanisms and queuing enhancements for deployment to a development LPAR. The shared daemon can be used by multiple users. It must be started before any user tries to start a build that uses the shared daemon.

For information about installing and configuring the shared daemon including the RACF security definitions that need to be implemented, see Configuring the shared and personal daemons.

Benefits of using a shared daemon

In a build environment that does not include a shared daemon, a JVM starts each time a user build is requested. The JVM stops when the user build completes and starts again when another user build starts to run. So total resource utilization can get high.

In a build environment that includes a shared daemon, a specified number of JVMs is configured. Regardless of the number of DBB user builds that are requested, only the specified number of JVMs is started. The build daemon handles all the incoming user build requests, sending each request to an available JVM. If all the JVMs are busy, the daemon sends the build requests that are not processed immediately to a queue and displays the position of the build request execution in the queue. This position moves up as the build execution carries on.

The shared daemon is focused on the following areas:

  • Performance.
    DBB user build requests are processed more efficiently thanks to the following mechanisms:
    • The processor usage from starting and stopping the JVMs is eliminated between builds.
      The shared daemon maintains a pool of JVMs available for incoming build requests. The number of JVMs at launch is dynamic. It can be configured and then modified during operation.
    • A built-in Groovy script caching is provided for every Groovy script execution. The result of each execution is cached to accelerate the next executions.
  • Scalability.
    With the automatic queuing of the build executions, dozens or hundreds of users can share a few JVMs. The administrator can define a maximum number of requests per queue and a maximum number of requests per user ID per queue.
  • Security.
    Security is ensured thanks to the following mechanisms:
    • The shared daemon includes several security mechanisms and checks to validate which user ID can use the build daemon and what functions it can execute.
    • The shared daemon client communicates with the shared daemon server through a local socket connection. The shared daemon server listens to a port for requests and sends output and responses from the build processes back to the shared daemon client through this local socket.

Accessing user-specific environment properties

The build processes that run in the shared daemon run under the authority of the user who requested the build. However, user-specific environment variables and their related Java system properties are created when the JVMs start up and refer to the user who started the shared daemon.

To retrieve user-specific variables for the user who requested the build, the Groovy scripts that access these values should instead use the corresponding DBB com.ibm.dbb.EnvVars static methods listed in the following table. These methods return the correct values when they are invoked in the shared daemon environment as well as invoked normally.

Environment variable Java System Property EnvVars Method
$HOME user.home EnvVars.getUserHome()
$LOGNAME user.name EnvVars.getUserName()
$PWD user.dir EnvVars.getUserDir()
$DBB_CONF N/A EnvVars.getDBBConf()

Example:

String HLQ = EnvVars.getUserName();

Running the shared daemon

Note: Before you can run the shared daemon a number of RACF security definitions need to implemented. For more information, see Security definitions for the shared daemon.

You can run the shared daemon by using any of the following methods:

  • Calling the shared daemon directly. You can see the usage by entering the following command:
/usr/lpp/IBM/dbb/lib/sdaemon -h

Note: The JAVA_HOME environment variable determines the Java™ version that is used to run the daemon. It defaults to the Java z/OS® UNIX installation directories if it is not set.

Issuing a command

To issue a command to the shared daemon, you must use the daemon client. The client can be accessed by using groovyz or calling the client directly (/usr/lpp/IBM/dbb/lib/sclient -h).

The following examples for using the shared daemon assume that you are using host 127.0.0.1 and port 8080. The actual host and port you use depends on your setup.

Note:

  • Use fully qualified file names when needed as an argument.
  • When issuing a command through the groovyz shell script, DBB_DAEMON_HOST and DBB_DAEMON_PORT are required.
  • To use with User Build, add the -DBB_DAEMON_HOST {your server host} and -DBB_DAEMON_PORT {your daemon port} options under the additional parameters section.

Executing using the groovyz process definition

The groovyz process definition executes a groovy script on the daemon. The groovy script must be the first parameter following the process definition name. Any subsequent arguments or options are passed directly to the executed groovy script.

Examples

  • groovyz -DBB_DAEMON_HOST 127.0.0.1 -DBB_DAEMON_PORT 8080 /u/example/build.groovy
  • sclient 127.0.0.1 8080 groovyz /u/example/build.groovy

Executing using the dbb process definition

The dbb process definition, added in version 3.0.1, is used to execute the DBB command line interface. It's command syntax is the same as when executed through the dbb shell script including support for user sessions. However, as starting a session is interactive, user sessions cannot be started through this interface.

The zBuilder may also be executed using this process definition.

Examples

  • sclient 127.0.0.1 8080 dbb list collections MortgageApplication
  • sclient 127.0.0.1 8080 dbb build full

By default, the groovyz shell script cannot call the dbb process definition. In order to do so, the user must replace the groovyz process definition passed to the client with dbb.

IE:
#daemon
...
$DBB_HOME/lib/sclient $DBB_DAEMON_HOST $DBB_DAEMON_PORT dbb "$@"
  • groovyz -DBB_DAEMON_HOST 127.0.0.1 -DBB_DAEMON_PORT 8080 build full

Managing processes

The daemon is a process coordinator that enables you to add and remove JVM processes.

For example, if more JVMs are needed, you can add another JVM process with the following command:

sclient 127.0.0.1 8080 groovyz add

Alternatively, if some JVMs are no longer needed, you can remove free JVMs with the following command:

sclient 127.0.0.1 8080 groovyz remove

If the daemon receives an exception from the script that it is running, that JVM process is restarted.

Additional information

Running multiple builds concurrently

The daemon can have multiple processes, which support multiple builds. For example, you can build two applications at the same time, or multiple people can run their own builds at the same time.

Handling return codes

Only the return codes from System.exit() calls in the Groovy build script are captured by the daemon. In other words, values returned by the Groovy build script by using return are not captured by the daemon.

Stopping the shared daemon

You can stop the shared daemon by using one of the following methods:

  • Using the background JCL job BGZSDSTP.jcl provided by DBB.
  • Using the stopdaemon.sh script. This script might require configuration to match the startdaemon.sh script that is used to initially start the shared daemon.

Note: The JAVA_HOME environment variable determines the Java version that is used to run the daemon. It defaults to the Java z/OS UNIX installation directories if it is not set.