User build with IBM Dependency Based Build (DBB)

User build

When you edit enterprise application code in Z Open Editor you get language support provided by our language servers giving 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 will go through many more stages after parsing providing much more information and warning messages of 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 of building 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 defining how programs should be build and an integration into VS Code to execute a build that will upload the program via 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 for setting up and running user build with DBB v2 and the Groovy scripts provided by the dbb-zappbuild Github repository in our IBM Knowledge Center.

User build with DBB v3

Dependency Based Build version 3 provides a new YAML based build scripting 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.

You, the developer, then performs 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 now building with DBB v3. It also still supports v2/v1 build scripts. It allows specifying local settings such as the HLQ to use for building or log file locations that the build engineer would not know about when creating the dbb-app.yaml file. It is also required to provide valid property groups in the ZAPP file so that the editor can find dependencies such as copybooks that 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 repo. 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

• how you can use variables from the Z Open Editor user settings to provide your specific HLQ to the build command
• how 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.
• how you specify which log files you wish to download after the build was 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 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

Item	Description	Example
dbbWorkspace	Required. The UNIX System Services location where all files get uploaded to. This folder might contain several application folders you are working on.	/u/ibmuser/projects
dbbHlq	Required. TSO high level qualifier(s) for your project.	IBMUSER.SAMPLE
dbbDefaultZappProfile	Optional. Name of the ZAPP profile to be used when running a User Build. If not defined User Build will use the 1st defined ZAPP dbb profile.	dbb-profile-1
localLogDir	Optional. Local directory where User Build logs will be downloaded. Path can be absolute or relative to the workspace of the build file. If not defined, User Build will download logs into a directory in your local workspace called logs	/Users/deb/dbb-logs

Once these files and settings are in place, a program was opened in the editor and its dependencies such as copybooks were 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 will upload all include files for the program, the program itself and all files listed under additionalDependencies in the ZAPP file before running 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 will only upload an include file if it was changed since the last time you ran a user build and it will not upload additionalDependencies anymore. It will just upload the program file and build it. If you require upload of the other files again, choose the first option.

Advanced problems view integration

In version before Z Open Editor v4, when you can ran a build of a program directly from inside Z Open Editor via the context menu the build would complete by downloading the build log files into the local development workspace. You would have to review the log file by opening it in the editor and scrolling through it.

If you enable Z Open Editor's advanced capabilities, Dependency Based Build log files will then be 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 will be 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 via a right-click on any message or automatically when you rerun a build.

The screenshot above shows an example of the Problems view reporting a warning about a RECORD IS VARYING statement not matching the required range. The problem could only be found by building the program. CCombining parse with user build errors and warnings gives developers new ways to determine problems they could not have before.