Building COBOL, PL/I, and HLASM applications tutorial

This tutorial demonstrates how to run a user build by using the IBM Z® Open Editor VS Code extension to build a simple COBOL, PL/I, or HLASM application from the zopeneditor-sample GitHub repository.

Learning objectives

This tutorial does not cover all capabilities of the user build functionality, but it demonstrates the procedure that you can follow to run a user build for COBOL, PL/I, and HLASM programs.

By completing the tutorial, you will learn：

  • How to set up user build settings in VS Code

  • How to run a user build

Tutorial scenario

The tutorial scenario is based on a fictitious company that has applications that are written in COBOL, PL/I, and HLASM. The traditional way of evoking a user build is though IBM Developer for z/OS®, an IDE that is based on Eclipse and provides integration of IBM Dependency Based Build. The company is moving toward a more lightweight IDE approach and is using VS Code for COBOL, PL/I, and HLASM development. A developer wants to edit, debug, and build their changes all within VS Code.

Time required

It takes approximately 20 minutes to complete this tutorial to set up user build settings in VS Code. It does not include the time to set up prerequisites if you have not done so.

Audience

This tutorial is for mainframe COBOL, PL/I, and HLASM developers who want to edit and build their applications in VS Code.

For Wazi Sandbox Trial Users DBB is already installed and configured on Wazi Sandbox. Shell scripts are provided to complete some of the prerequisite activities. Running a user build on Wazi Sandbox instructions are provided.

Prerequisites

Ensure that your client and host meet the following prerequisites.

Prerequisites on client

  1. Clone the zopeneditor-sample GitHub repository by issuing the following command in a command-line window:

    git clone git@github.com:IBM/zopeneditor-sample.git

  2. If you have an RSE API connection to your host, you can use the included zowecli-create-profiles.sh script to create both RSE and SSH Zowe™ profiles.

    • Open the script and replace the parameter values with your values.

    • In the terminal window, run the script:

    . SCRIPTS/zowecli-create-profiles.sh

    Learn more about creating RSE profiles.

  3. If you connect to your host via z/OSMF, use the following commands to create your Zowe CLI and SSH profiles:

    zowe profiles create zosmf-profile myZoweCLIProfile --host <hostname> --port <portnum> --user <userid> --pass <pw> --reject-unauthorized false

    Learn more about creating z/OSMF profile.

    Create a Zowe SSH profile:

    zowe profiles create ssh-profile mySSHProfile --host <host-name> --port <port> --user <user> --pass <pass>

    You just created two Zowe profiles, a Zowe CLI profile called myZoweCLIProfile and another SSH profile called mySSHProfile.

Prerequisites on host

  1. You have IBM Dependency Based Build (DBB) toolkit installed and configured on a z/OS system as described in Installing and configuring host components.

  2. You are connected to the host as described in Setting up integration to interact with z/OS. In this tutorial, you are assumed to have installed and configured RSE API as the host component for z/OS connection.

  3. In your workspace, switch to the wazi-main branch of the zopeneditor-sample repo.

  4. Open the application-conf/datasets-sandbox.properties file and update all of the data set names according to your z/OS host. Refer to documentation in the dbb-zappbuild Github repository for details.

  5. Open the dbb-prepare-uss-folder.sh script and verify the parameter values for your z/OS host.

  6. In the terminal window, run the script:

    . SCRIPTS/dbb-prepare-uss-folder.sh

    It will:

    • Create a project folder /u/ibmuser/projects where the source code will be uploaded and built.

    • Clone the DBB zAppBuild repo to the uss working directory. zAppBuild is a generic build solution for building z/OS applications by using Apache Groovy build scripts and IBM Dependency Based Build (DBB) APIs.

    • Upload the datasets-sandbox.properties file to dbb-zappbuild/build-conf/datasets.properties

Setting up a user build in VS Code

Before you run a user build, complete the following procedure.

  1. Open the zopeneditor-sample folder in VS Code by clicking File > Add Folder to Workspace and choosing zopeneditor-sample.

  2. Open IBM Z Open Editor VS Code User Settings.

    • On Windows or Linux®, click File > Preferences > Settings

    • On macOS, click Code > Preferences > Settings

    For more information about VS Code User Settings, see VS Code documentation.

  3. On the left side, navigate to the Extensions view, and click IBM Z Open Editor. Alternatively, open the Settings page, use the search bar at the top of the page to search for IBM Z Open Editor, and scroll until you find Userbuild: User Settings.

  4. Add the following user settings:

    Item Description Example
    dbbWorkspace USS location of the parent project folder. This folder might contain several application folders you are working on. /u/ibmuser/projects
    dbbHlq TSO high level qualifier(s) for your project. IBMUSER.SAMPLE
    dbbLogDir Directory on z/OS where user build logs will be stored. /u/ibmuser/projects/zopeneditor-sample/logs

  5. Check project-related settings in the zopeneditor-sample/.vscode/settings.json file. Make sure they match what's on your host system. Note that some values have variables surrounded by ${}. The User Settings you just added will be used to populate these variables.

  6. (Optional) Specify which Zowe CLI profiles should be used for user builds. If these are not defined, then the build process will search for a default profile set by Zowe, looking first for an RSE default profile. If one is not found, it will then search for a default z/OSMF profile. It will also search for default SSH profile.

    In User Settings, navigate to the Extensions view, and click IBM Z Open Editor. Scroll down to the Zowe section and add the profile names you have created according to the Prerequisites section:

    Item Value
    defaultCliProfile myZoweCLIProfile
    defaultSshCliProfile mySSHProfile

Building a COBOL, PL/I, or HLASM application from zopeneditor-sample repository

  1. Switch to the wazi-main branch of your downloaded zopeneditor-sample project. This branch has the necessary configuration files for user build.

    1. cd into the zopeneditor-sample directory that was just cloned.

    2. Switch to the wazi-main branch by using the following command.

      git checkout wazi-main

    Now you are ready to run a user build from VS Code.

  2. Open one of the following files in VS Code.

    • zopeneditor-sample/COBOL/SAM1.cbl

    • zopeneditor-sample/PLI/PSAM2.pli

    • zopeneditor-sample/ASM/ASAM1.asm

    Note: When using the zopeneditor-sample repository, PSAM2.pli will need to be built prior to building PSAM1.pli in order for the linkedit step to complete successfully.

  3. Right-click inside the file to view the user build options. You can find three user build options in the pop-up menu:

    • Run IBM User Build

    • Run IBM User Build with full upload

    • Run Setup for IBM User Build

  4. Click Run Setup for IBM User Build. This option uploads the application-conf folder to z/OS and creates zopeneditor-sample inside /u/user/projects if it does not exist.

    You will see output similar to the following text:

    =====================
Running setup for user build...
Setup will upload files or folders defined in your ZAPP file or in .vscode/settings.json under "zopeneditor.userbuild.userSettings.additionalDependencies".
Checking ZAPP file or workspace settings...
DBB ZAPP or workspace settings should be defined in either your repository's zapp.yaml, zapp.json or .vscode/settings.json file.
    command: $DBB_HOME/bin/groovyz
    buildScriptArgs: --userBuild,--workspace /u/user/projects,--application zopeneditor-sample,--hlq USER.SAMPLE,--outDir /u/user/projects/zopeneditor-sample/logs
    buildScriptPath: /u/user/projects/dbb-zappbuild/build.groovy
    additionalDependencies: application-conf
---------------------
Checking user settings...
User settings should be defined in your VS Code or Theia Settings under zopeneditor.userbuild.userSettings
    localWorkspacePath: **Optional setting is missing**
    dbbWorkspace: /u/user/projects
    dbbHlq: USER.SAMPLE
    dbbLogDir: /u/user/projects/logs
---------------------
Using ssh profile mySSHProfile
Using zowe profile profile myCLIProfile
Identified local root workspace path as /Users/user/wazi/zopeneditor-sample
Running setup to build /Users/user/wazi/zopeneditor-sample/COBOL/SAM1.cbl program.
Executing ssh command:
mkdir -p '/u/user/projects/zopeneditor-sample'
$
Uploading additional dependencies...
Uploading /Users/user/wazi/zopeneditor-sample/application-conf
Executing ssh command:
mkdir -p '/u/user/projects/zopeneditor-sample/application-conf'
$
User build setup FINISHED.

  5. Right-click inside the program file in the editor again and select Run IBM User Build.

    You will see output similar to the following text:

    =====================
Running user build...
Identified local root workspace path as /Users/user/zopeneditor-sample
---------------------
Checking workspace settings...
Workspace settings should be defined in your repository's .vscode/settings.json file under zopeneditor.userbuild.workspaceSettings.dbb
   command: $DBB_HOME/bin/groovyz
   buildScriptArgs: --userBuild,--workspace /u/user/projects,--application wazi-sample,--hlq USER.SAMPLE,--outDir /u/user/projects/zopeneditor-sample/logs
   buildScriptPath: /u/user/zAppBuild/build.groovy
   additionalDependencies: application-conf
---------------------
Checking user settings...
User settings should be defined in your VS Code or Theia Settings under zopeneditor.userbuild.userSettings
   localWorkspacePath: **Optional setting is missing**
   dbbWorkspace: /u/user/projects
   dbbHlq: USER.SAMPLE
   dbbLogDir: /u/user/projects/zopeneditor-sample/logs
---------------------
Using ssh profile mySSHProfile
Using zowe profile profile myZoweCLIProfile
Executing ssh command:
mkdir -p /u/user/projects/zopeneditor-sample/COBOL
Uploading /Users/user/zoweDev/zopeneditor-sample/COBOL/SAM1.cbl program.
Found total of 2 local copybooks.
Checking if copybook files were updated since last build...
Executing ssh command:
mkdir -p /u/user/projects/zopeneditor-sample/COPYBOOK
Updating 2/2 local copybooks.
Uploading /Users/user/zopeneditor-sample/COPYBOOK/CUSTCOPY.cpy
Uploading /Users/user/zopeneditor-sample/COPYBOOK/TRANREC.cpy
---------------------
Executing ssh command:
$DBB_HOME/bin/groovyz /u/user/zAppBuild/build.groovy --userBuild --workspace /u/user/projects --application zopeneditor-sample --hlq USER.SAMPLE --outDir /u/user/projects/zopeneditor-sample/logs /u/user/projects/zopeneditor-sample/COBOL/SAM1.cbl
$
** Build start at 20200820.101012.010
** Build output located at /u/user/projects/zopeneditor-sample/logs
** Adding /u/user/projects/zopeneditor-sample/COBOL/SAM1.cbl to Building build list
** Writing build list file to /u/user/projects/zopeneditor-sample/logs/buildList.txt
** Invoking build scripts according to build order: BMS.groovy,Cobol.groovy,Assembler.groovy,PLI.groovy,LinkEdit.groovy
** Building files mapped to BMS.groovy script
** Building files mapped to Cobol.groovy script
*** Building file zopeneditor-sample/COBOL/SAM1.cbl
** Building files mapped to Assembler.groovy script
** Building files mapped to PLI.groovy script
** Building files mapped to LinkEdit.groovy script
** Writing build report data to /u/user/projects/zopeneditor-sample/logs/BuildReport.json
** Writing build report to /u/user/projects/zopeneditor-sample/logs/BuildReport.html
** Build ended at Thu Aug 20 10:10:18 EDT 2020
** Build State : CLEAN
** Total files processed : 1
** Total build time  : 5.441 seconds
** Build finished
Looking for user-build logs in "/u/user/projects/zopeneditor-sample/logs".
Downloading logs to /Users/user/zopeneditor-sample/logs
Downloading log file /u/user/projects/zopeneditor-sample/logs/buildList.txt. Binary: false
Downloading log file /u/user/projects/zopeneditor-sample/logs/SAM1.log. Binary: false
Downloading log file /u/user/projects/zopeneditor-sample/logs/BuildReport.json. Binary: true
Downloading log file /u/user/projects/zopeneditor-sample/logs/BuildReport.html. Binary: true
Downloading log file /u/user/projects/zopeneditor-sample/logs/SAM2.log. Binary: false
Downloading of 5 log files to /Users/user/zopeneditor-sample/logs finished successfully.

  6. Check your local repository for log files. The build created a logs folder in the local zopeneditor-sample directory and downloaded build log files from z/OS.

    To avoid committing changes in the logs folder, you can add it to .gitignore so Git would not show new changes in the repository when you run builds.