Configuring the Build Flow

This section describes the flow that is executed when you run a build. The first diagram illustrates the flow on a distributed platform, the second diagram illustrates the flow on an MVS platform. The steps in the table that follows refer to both diagrams. The table also includes information about how you can configure each step in the flow.

Figure 3-1. The Build Flow on Distributed Platforms

Figure 3-2. The Build Flow on MVS Platforms

Step | Description | How can I configure this step?
1 | The build process begins when a Dimensions client sends a build request via the BLD or BLDB commands to the Dimensions server. The command is then submitted to the deployment server and placed in the pending queue for the build area along with all other build and deployment jobs for that area. The command waits in the queue for its turn to be executed. When its turn arrives the deployment server sends the command back to the Dimensions server. | For information about configuring the build commands, see the Command-Line Reference. For information about the deployment server, see the Dimensions CM online help.
2 | The Dimensions server sends a SOAP build request to the Build Management Server with all the necessary information required to run the build (targets, scripts, build areas, build options, etc.). | You can configure the location of the Build Management Server in the following variables in the Dimensions configuration file dm.cfg: DM_WEB_URL: specifies the URL of the default build server. DM_BUILDERWS_URL: specifies the URL of a build server that is different from the default (if the default is not defined, this location is used). For more information see: Build Configuration Symbols Load Balancing a Build Server Administration Guide
3 | The Build Management Server contacts the Dimensions server and instructs it to transfer the required sources, using the services of the Dimensions Listener, to the build area. | Use the /POPULATE_SCOPE qualifier with the BLD command to populate the build areas. The sources that are transferred depend on the definitions in the build request and the build configuration. For more information see the Command-Line Reference.
4 | The Build Management Server gathers all the information about the build being requested and places it in a Build Request Definition (BRD) file. | You can configure the BRD file by changing the variables in the file web.xml located in: $DM_ROOT\Common Tools\tomcat\<version>\webapps\bws\WEB-INF For information see: Customizing a Build Server Administration Guide
5 | The Build Management Server transfers the BRD file to a temporary location on the build node performing the build via the Dimensions Listener. The Dimensions Listener or Agent then uses a Dimensions REXEC command to invoke an execution of the Primary Build Monitor (PBEM) on that node. The main job of the PBEM is to oversee and control the build process from start to finish. | You can specify where the BRD file is written by configuring the variable DM_TMP in the Dimensions configuration file, dm.cfg, on the build agent node. For information about DM_TMP see the Administration Guide.
6 | The PBEM is started via a Dimensions template. The Dimensions Listener then expands the PBEM template and invokes the resulting script (for example, .bat, .sh, and JCL) using the build template library as required. | You can modify the Dimensions templates as required. For information about the Dimensions templating language and the build templates see Part 4 of the Developer’s API Reference. For information about the PBEM and its command parameters see The Primary Build Execution Monitor.
7 | Distributed: The PBEM parses the BRD to determine the build steps to be executed, expands the build templates (7a) for each step, and invokes each step (7b) as necessary. Mainframe: For each build step in the BRD the PBEM performs a process called Build Optimization. This process determines whether the given step needs to execute. For each build step that needs to execute, the build template file that is required to build the step is expanded and executed. | In each build configuration you specify the name of the required build template(s). You can configure the location the of the build templates in the variable DM_TEMPLATE_CATALOG in the Dimensions configuration file. For more information see chapter 7 in the Developer’s API Reference.
8 | As each build step executes it accesses local metadata (8a) and the build area(s) (8b) to complete the build. As each build step completes, it communicates with the PBEM (8c). The PBEM communicates with the Build Management Server which collects the Bill of Materials (BOM) (8d), collects the build logs, and displays the current status to the user. The BOM is optional on distributed platforms. On a mainframe most of the templates run in the context of a Secondary Build Execution Monitor (SBEM). The main job of the SBEM is to: Oversee and execute a given build step by expanding additional templates as required. Respond to any directives that are in the build template. As a build template is prepared for execution it can initiate the Dependency Monitor to watch specified DD cards for activity and record the results. This information goes in the BOM report to be used later. The build task is then run, outputs are created in the build areas, local metadata is updated, and the final progress and log files are reported back to the PBEM on completion. | On MVS, metadata is defined by environment variables. For information, see Chapter 2, Installing Dimensions for z/OS, and Appendix D, Setting up Dimensions Metadata, in the Dimensions for z/OS Guide. On distributed systems, metadata is saved in the same location as the files. For more information, see the Dimensions CM online help and the Administration Guide. For information about build footprinting and the BOM, see Creating and Embedding Build Footprinting.
9 | After all the build steps have completed, the PBEM communicates a final status to the Build Management Server and closes. |
10 | Output collection retrieves the items from the build area back to the Dimensions repository. Output collection is based on one of the following: Area scanning (no BOM is provided). Using the BOM to determine which targets need to be checked back into Dimensions. Output collection is an optional step. | You can trigger output collection using the /CAPTURE qualifier with the BLD command. For information, see the Command-Line Reference. Upload rules and preservation policies determine what items are checked back into Dimensions and how. For information see the Administration Console online help.