User build with IBM Dependency Based Build (DBB)

When you edit enterprise application code in Z Open Editor, you get language support provided by our language servers that gives you code completion and real-time syntax errors. However, the language servers utilized in Z Open Editor can only identify problems that a parser can detect such as basic syntax errors. A compiler goes through many more stages after parsing, provides much more information and warning messages to problems that a parser cannot detect. Therefore, sometimes it is necessary to actually build the program and review the compiler output to ensure your program is correct, limited of course to what the compiler can detect without actually running tests.

For a seamless user experience to build for developers, Z Open Editor provides an integration with IBM® Dependency Based Build called "user build". It allows team members to share a configuration file which defines how to build programs and an integration into VS Code to execute a build that uploads the program through Zowe™ Explorer with its dependencies to z/OS®, execute the build, and download build logs to be presented in the editor.

We provide detailed documentation to set up and run user build with DBB v2 and the Groovy scripts provided by the dbb-zappbuild Github repository in our IBM Knowledge Center.

Dependency Based Build version 3 provides a new YAML based build script framework called zBuilder. With zBuilder the setup and configuration work for developers has been vastly simplified. The assumption is that build scripts and configuration files have been provided by the team lead or build engineer on z/OS together with the DBB installation. Developers only have to configure the location of files and basic settings such as their personal HLQ for the user build to be executed from Z Open Editor.

See the DBB v3 zBuilder document for an overview of the five basic z/OS setup steps. Step 4 talks about creating the dbb-app.yaml file which is shared with developer together with a ZAPP profile for the build.

The developer can perform the following setup steps in Z Open Editor:

1. Setup your UNIX System Services profile: As the remote build execution is done on the z/OS UNIX system, some basic environment variables have to be configured to be able to run the build. The minimum set is DBB_HOME, DBB_CONF, and DBB_BUILD. See the DBB environment variables page with details.

2. Create a zapp.yaml file with a DBB v3 build profile: The dbb ZAPP profile type has been extended with Z Open Editor v5 to support build with DBB v3. It also supports v2/v1 build scripts. It allows to specify local settings such as the HLQ to use build or log file locations that the build engineer does not know about, when the dbb-app.yaml file is created. It is also required to provide valid property groups in the ZAPP file so that the editor can find dependencies such as copybooks, it then uploads together with the program file for the build.

3. Provide the dbb-app.yaml for your application: Add the dbb-app.yaml provided by your build engineer in your workspace folder next to the zapp.yaml file.

You can find examples for a (2) and (3) in our Github sample repository. We show how such files could look like in a single root workspace as well as multi-root workspace.

A ZAPP profile for DBB v3 that you can find in these samples looks like this

profiles:
  - name: zBuilder-userbuild
    type: dbb
    settings:
      command: "$DBB_HOME/bin/dbb build"
      lifecycle: user
      lifecycleArgs:
        - "--hlq ${zopeneditor.userbuild.userSettings.dbbHlq}"
      additionalDependencies:
        - "dbb-app.yaml"
      logFilePatterns:
        - "${buildFile.basename}-*.log"
        - "BuildReport.*"

The example shows:

• You can use variables from the Z Open Editor user settings to provide your specific HLQ to the build command.

• You can specify additional dependencies, which are file or folders that should be uploaded with the program file that are also required for the build. This could be the dbb-app.yaml file itself or BMS files for a CICS application.

• You can specify which log files you wish to download after the build is executed. These files are optional downloads for the user in addition to the logs automatically retrieved for the Problems view as described in the next section.

In Z Open Editor you can use the Settings page to configure variables such as the dbbHlq variable shown in the example above.

1. Open VS Code settings and search for "user build", you can see two settings.

2. Select the checkbox if not selected to enable user build.

3. In the second setting called "Userbuild: User Settings" you can click the "Add Item" button to provide the settings shown below.

| dbbDefaultZappProfile | Optional. Name of the ZAPP profile to be used when you run a User Build. If not defined, User Build uses the 1st defined ZAPP dbb profile. | dbb-profile-1 | | localLogDir | Optional. Local directory where User Build logs are downloaded. Path can be absolute or relative to the workspace of the build file. If not defined, User Build downloads logs into a directory in your local workspace called logs | /Users/deb/dbb-logs|

Once these files and settings are in place, a program is opened in the editor and its dependencies such as copybooks are found as specified in the ZAPP file. The user can run a user build by right-clicking inside the editor and selecting one of these commands from the context menu:

• Run IBM User Build with full upload: which is the required command to run at the first execution of a user build for a particular program. This command uploads all include files for the program, the program itself and all files listed under additionalDependencies in the ZAPP file before you run the build command specified in the ZAPP file.

• Run IBM User Build: is the command you can run at subsequent executions of the build that provides a faster execution, because it only uploads an include file if it was changed since the last time you ran a user build and it does not upload additionalDependencies anymore. It just uploads the program file and builds it. If you require to upload the other files again, choose the first option.

By default, user build commands are only available for COBOL, HLASM, and PL/I files. To show user build commands in context menus and the command palette for all files (excluding include files and copybooks), you can set the zopeneditor.userbuild.alwaysShowCommands setting to true. This allows users to a run user build with a custom Groovy and zBuilder script on files of other languages. This setting is experimental and may result in unexpected Z Open Editor behavior when you run a user build on non-COBOL, HLASM, or PL/I programs.

In version before Z Open Editor v4, when you run a build of a program directly from inside Z Open Editor through the context menu, the build completes by downloading the build log files into the local development workspace. Open the editor, review the log file and scroll through it.

If you enable Z Open Editor's advanced capabilities, Dependency Based Build log files are then parsed by Z Open Editor and presented as errors and warnings in the regular VS Code Problems view. You can click entries in the Problems view to directly navigate to the line in the code for which the problem was reported. These error is shown next to regular Z Open Editor errors side-by-side, but you can distinguish them by the compiler error number displayed next to them.

The Problems view can be cleared manually through a right-click on any message or automatically when you rerun a build.

The screenshot above shows an example of the Problems view that reports a warning about a RECORD IS VARYING statement not matching the required range. The problem can only be found if the program is built. Combining parse with user build errors and warnings gives developers new ways to determine problems they could not identify before.