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. 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

  3. Make sure you create a Zowe Team Configuration file that defines profiles that allow you to connect to zOS. If you connect to zOS via z/OSMF, ensure your configuration file contains an SSH connection. The simplest way to create a Configuration file is via Zowe Explorer "Add Profile" button. Choose "Create a New Team Configuration File" option. Learn how to create Team configuration profiles via command line here.

    Note: Using old V1 profiles is still supported, however it's recomended to use new Team Configuration file instead. The following instructions are for creating V1 profiles. 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:

  ``` ascii
  . SCRIPTS/zowecli-create-profiles.sh
  ```

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

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

  Learn more about creating [z/OSMF profile](https://docs.zowe.org/stable/web_help/docs/zowe_profiles_create_zosmf-profile.html).


  Create a Zowe SSH profile:

  ```ascii
  zowe profiles create ssh-profile mySSHProfile --host <host-name> --port <port> --user <user> --pass <pass>
    
Running the two commands above creates two Zowe profiles; a Zowe CLI profile called `myZoweCLIProfile` and an 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. 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.

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

  5. 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 your z/OS UNIX System Services 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 z/OS UNIX System Services 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
    dbbDefaultZappProfile Name of the ZAPP profile to be used when running a User Build  
    localLogDir Local directory where User Build logs will be downloaded. Path can be absolute or relative to the workspace of the build file.  

  5. Check project-related settings in the zopeneditor-sample/zapp.yaml 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. Hover over the key items in the ZAPP file to learn what each setting does.

  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. 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.

  2. 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

  3. 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 under "additionalDependencies".
Checking DBB profile settings defined in your repository's zapp.yaml or zapp.json
User setting dbbDefaultZappProfile: **undefined**
Will read settings from the first dbb profile found in your ZAPP file.
  application: SAM
  command: $DBB_HOME/bin/groovyz -DBB_PERSONAL_DAEMON
  buildScriptArgs: --userBuild,--workspace /u/user,--application SAM,--hlq KTOPCHI.SAMPLE,--outDir /u/user/logs,--dependencyFile ${dependencyFile}
  buildScriptPath: /u/user/dbb-zappbuild/build.groovy
  additionalDependencies: application-conf,zapp*
  logFilePatterns: SAM1.log,BuildReport.*
---------------------
Checking user settings...
User settings should be defined in your VS Code or Theia Settings under zopeneditor.userbuild.userSettings
  dbbWorkspace: /u/user
  dbbHlq: USER.SAMPLE
  dbbLogDir: /u/user/logs
  dbbDefaultZappProfile: **Optional setting is missing**
  localLogDir: **Optional setting is missing**
Using .gitattributes file at /Users/user/wazi-sample/.gitattributes
---------------------
Searching for the default Zowe CLI profile...
Using Zowe profile rse
Checking if RSE API profile rse can connect:
Connected successfully.

Identified the local root workspace path as /Users/user/wazi-sample
Running setup to build /Users/user/wazi-sample/COBOL/SAM1.cbl program.
Executing unix command 
mkdir -p '/u/user/SAM' at path 
/u/user

Executing unix command 
mkdir -p '/u/user/logs' at path 
/u/user

Uploading additional dependencies matched inside workspace of the build file ...
Matching files for application-conf 
/Users/user/wazi-sample/application-conf
Matching files for zapp* 
/Users/user/wazi-sample/zapp-example.json
/Users/user/wazi-sample/zapp.yaml
Executing unix command 
mkdir -p '/u/user/SAM' at path 
/u/user
Executing unix command 
mkdir -p '/u/user/SAM' at path 
/u/user
Executing unix command 
mkdir -p '/u/user/SAM/application-conf' at path 
/u/user

No encoding was found in .gitattributes file for /Users/user/wazi-sample/zapp.yaml
Uploading file /Users/user/wazi-sample/zapp.yaml to /u/user/SAM/zapp.yaml with default encoding

Uploading directory /Users/user/wazi-sample/application-conf to /u/user/SAM/application-conf

No encoding was found in .gitattributes file for /Users/user/wazi-sample/zapp-example.json
Uploading file /Users/user/wazi-sample/zapp-example.json to /u/user/SAM/zapp-example.json with default encoding
Finished running setup for User Build.

  4. 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 the local root workspace path as /Users/user/wazi-sample
---------------------
Checking DBB profile settings defined in your repository's zapp.yaml or zapp.json
User setting dbbDefaultZappProfile: **undefined**
Will read settings from the first DBB profile found in your ZAPP file.
   application: SAM
   command: $DBB_HOME/bin/groovyz -DBB_PERSONAL_DAEMON
   buildScriptArgs: --userBuild,--workspace /u/user,--application SAM,--hlq KTOPCHI.SAMPLE,--outDir /u/user/logs,--dependencyFile ${dependencyFile}
   buildScriptPath: /u/user/dbb-zappbuild/build.groovy
   additionalDependencies: application-conf,zapp*
   logFilePatterns: SAM1.log,BuildReport.*
---------------------
Checking user settings...
User settings should be defined in your VS Code or Theia Settings under zopeneditor.userbuild.userSettings
   dbbWorkspace: /u/user
   dbbHlq: KTOPCHI.SAMPLE
   dbbLogDir: /u/user/logs
   dbbDefaultZappProfile: **Optional setting is missing**
   localLogDir: **Optional setting is missing**
Using .gitattributes file at /Users/user/wazi-sample/.gitattributes
---------------------
Searching for the default Zowe CLI profile...
Using Zowe profile rse
Checking if RSE API profile rse can connect:
Connected successfully.

Executing unix command 
mkdir -p '/u/user/SAM/COBOL' at path 
/u/user

Uploading file /Users/user/wazi-sample/COBOL/SAM1.cbl to /u/user/SAM/COBOL/SAM1.cbl with encoding ibm-1047
Fetching build file dependencies...
Found a total of 2 local include files:
/Users/user/wazi-sample/COPYBOOK/TRANREC.cpy
/Users/user/wazi-sample/COPYBOOK/CUSTCOPY.cpy
Executing unix command 
mkdir -p '/u/user/SAM/COPYBOOK' at path 
/u/user

Checking if include files were updated since the last build...
Updating 2/2 local include files.
Uploading file /Users/user/wazi-sample/COPYBOOK/TRANREC.cpy to /u/user/SAM/COPYBOOK/TRANREC.cpy with encoding ibm-1047
Uploading file /Users/user/wazi-sample/COPYBOOK/CUSTCOPY.cpy to /u/user/SAM/COPYBOOK/CUSTCOPY.cpy with encoding ibm-1047
---------------------
Generating the local dependencies file for this build in /Users/user/Library/Application Support/Code/logs/20221107T111641/window4/exthost/IBM.zopeneditor/.userbuilddependencies
No encoding found for *.userbuilddependencies. Assigning default encoding of utf-8
Uploading file /Users/user/Library/Application Support/Code/logs/20221107T111641/window4/exthost/IBM.zopeneditor/.userbuilddependencies to /u/user/logs/.userbuilddependencies with encoding utf-8
Executing unix command 

---------------------
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.

  5. 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.