Building COBOL applications tutorial

This tutorial does not cover all features of IBM User Build, but it demonstrates the procedure that you can follow to run a user build for COBOL programs.

By completing the tutorial, you can learn about：

• How to set up IBM User Build settings in VS Code

• How to run a user build

The tutorial scenario is based on a fictitious company that has applications that are written in COBOL. The traditional way of evoking 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 towards a more lightweight IDE approach and is using VS Code for COBOL development. A COBOL developer wants to edit, debug, and build their changes all within VS Code.

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

This tutorial is for mainframe COBOL developers who want to edit and build their COBOL applications in VS Code.

Ensure that your host and client meet the following prerequisites.

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

1. Open the zopeneditor-sample folder in VS Code.

2. Open IBM User Build 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 Extensions, and click on IBM User Build. This will open IBM User Build 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/user/projects
   dbbHlq	TSO high level qualifier(s) for your project.	USER.SAMPLE
   dbbLogDir	Directory on z/OS where user build logs will be stored.	/u/user/projects/zopeneditor-sample/logs
   localWorkspacePath	Optional parameter. VS Code will automatically determine your Git project root folder. If you have an unconventional setup and VS Code does not correctly identify your workspace root path, use this option to tell VS Code where your project root path is. You need to define this setting when using IBM User Build from CodeReady Workspaces.	/Users/user/zopeneditor-sample

5. Check project-related settings in the zopeneditor-sample/.vscode/settings.json file. Notice 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 Build. 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, and 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 Extensions, and click on Z Open Editor. Scroll down to Zowe section and add the profile names you have created according to the Prerequisites section:

   Item	Value
   defaultCliProfile	myZoweCLIProfile
   defaultSshCliProfile	mySSHProfile

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

1. Open the zopeneditor-sample/COBOL/SAM1.cbl file in VS Code.

2. Right-click inside the file to view IBM 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

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

2. Right-click inside SAM1.cbl again and click 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.

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

For troubleshooting, refer to Building COBOL programs with user build.