Running user build

After you set up the prerequisites, complete the procedure below to run a user build for z/OS® programs.

Note: Refer to the appropriate section for your z/OS programs and ensure you have correct setup to build each type of program.

1. Verify settings for z/OS programs

Verify settings for COBOL programs

  1. Verify the copybookRule setting in the application.properties file.

    1. Open the application.properties file in the application-conf folder in the VS Code workspace.

    2. Search on copybookRule and verify the z/OS UNIX System Services location.

      The default z/OS UNIX System Services location is as follows:

      {"sourceDir": "${workspace}", "directory": "${application}/copybook"}

    The user build functionality creates z/OS UNIX System Services folders that align with the VS Code workspace subfolders. For example, if your workspace copybook folder is zopeneditor-sample/COPYBOOK, then the z/OS UNIX System Services folder location will also be under zopeneditor-sample/COPYBOOK. Therefore, the z/OS UNIX System Services location in the copybookRule needs to match the z/OS UNIX System Services location generated during the user build process. In this example, the value should be:

    {"sourceDir": "${workspace}", "directory": "${application}/COPYBOOK"}

Verify settings for PL/I programs

  1. Verify the plincRule setting in the application.properties file.

    1. Open the application.properties file in the application-conf folder in the VS Code workspace.

    2. Search on plincRule and verify the z/OS UNIX System Services location.

      The default z/OS UNIX System Services location is as follows:

      {"sourceDir": "${workspace}", "directory": "${application}/plinc"}

    The user build functionality creates z/OS UNIX System Services folders that align with the VS Code workspace subfolders. For example, if your workspace include folder is zopeneditor-sample/INCLUDES, then the z/OS UNIX System Services folder location will also be under zopeneditor-sample/INCLUDES. Therefore, the z/OS UNIX System Services location in the plincRule needs to match the z/OS UNIX System Services location generated during the user build process. In this example, the value should be:

    {"sourceDir": "${workspace}", "directory": "${application}/INCLUDES"}

    Note: When using the zopeneditor-sample repository, you must first build PSAM1.pli before you build PSAM2.pli in order for the linkedit step to complete successfully.

Verify settings for HLASM programs

  1. Verify the asmCopyRule setting in the application.properties file.

    1. Open the application.properties file in the application-conf folder in the VS Code workspace.

    2. Search on asmCopyRule and verify the z/OS UNIX System Services location.

      The default z/OS UNIX System Services location is as follows:

      {"sourceDir": "${workspace}", "directory": "${application}/asmcopy"}

    The user build functionality creates z/OS UNIX System Services folders that align with the VS Code workspace subfolders. For example, if your workspace copybook and macro folder is zopeneditor-sample/ASMCOPY, then the z/OS UNIX System Services folder location will also be under zopeneditor-sample/ASMCOPY. Therefore, the z/OS UNIX System Services location in the asmCopyRule needs to match the z/OS UNIX System Services location generated during the user build process. In this example, the value should be:

    {"sourceDir": "${workspace}", "directory": "${application}/ASMCOPY"}

2. Running a user build

  1. Right-click in the program that is opened in the editor and select Run Setup for IBM User Build.

    The files listed in the additionalDependencies setting will be copied from your local workspace to the z/OS UNIX System Services locations. You need to run this task only once unless other additional dependencies are needed later.

  2. There are two options for running a user build.

    • Run IBM User Build with full upload - Upload all local copybooks referenced in the program and the additional dependencies defined in your ZAPP file. Use this option when you need to reupload all of the local copybooks to the z/OS UNIX System Services application folder or when the dependencies have changed.

    • Run IBM User Build - Upload only the copybooks that need to be uploaded, such as any new copybooks introduced into the program and the copybooks that have been modified since the last upload. You are supposed to use this option most often for efficiency since it does not upload all copybooks.

      Option 1 - Select Run IBM User Build with full upload. This process determines the copybook dependencies and uploads all local ones along with the COBOL file to the z/OS UNIX System Services file system, and then executes the DBB build script. Since this option will upload all of the copybooks, it should only be used when it is necessary to actually upload all of the copybooks. The COBOL program and copybooks being uploaded will be listed in the output console window as shown below:

      =====================
Running user build...
Identified local root workspace path as c:\Users\userid\wazi-sample
Uploading c:\Users\userid\wazi-sample\COBOL\SAM1.cbl program.
Found total of 2 local copybooks.
Updating 2/2 local copybooks.
Uploading c:\Users\userid\wazi-sample\COPYBOOK\CUSTCOPY.cpy
Uploading c:\Users\userid\wazi-sample\COPYBOOK\TRANREC.cpy

      Option 2 - Select Run IBM User Build. This process determines which copybooks have been modified or are new since the last build and will only upload modified and new copybooks with the COBOL file to the z/OS UNIX System Services file system. It then executes the DBB build script. The COBOL program and copybooks being uploaded will be listed in the output console window as shown below:

      =====================
Running user build...
Identified local root workspace path as c:\Users\userid\wazi-sample
Uploading c:\Users\userid\wazi-sample\COPYBOOK\CUSTCOPY.cpy program.
Found total of 2 local copybooks.
Checking if copybook files were updated since last build...
Updating 0/2 local copybooks.

The DBB build output will also indicate the results of the build in the output console window. A successful build will show a message similar to the following:

** Build ended at Fri Feb 14 08:58:19 EST 2020

** Build State : CLEAN

** Total files processed : 1

** Total build time  : 14.877 seconds

** Build finished

Looking for user-build logs in /u/userid/projects/wazi-sample/logs
Downloading logs to c:\Users\userid\wazi-sample\wazi-sample\logs
Downloading log file /u/userid/projects/wazi-sample/logs/buildList.txt. Binary: false
Downloading log file /u/userid/projects/wazi-sample/logs/BuildReport.html. Binary: true
Downloading log file /u/userid/projects/wazi-sample/logs/BuildReport.json. Binary: true
Downloading log file /u/userid/projects/wazi-sample/logs/SAM1.log. Binary: false
Downloading of 4 log files to c:\Users\userid\wazi-sample\wazi-sample\logs finished successfully.

The user build functionality will automatically download logs from z/OS into the logs directory on your local workspace. The logs folder will be created if it does not exist.

If you see an ERROR build result, you can view the log produced by DBB. The log is in the z/OS UNIX System Services folder defined in the --outDir setting listed above.

** Build ended at Fri Feb 14 09:08:37 EST 2020

** Build State : ERROR

** Total files processed : 1

** Total build time  : 13.552 seconds


** Build finished

Looking for user-build logs in /u/userid/projects/zopeneditor-sample/logs
Downloading logs to c:\Users\userid\zopeneditor-sample\logs
...

Locating the log file of user build output

IBM Developer for z/OS on VS Code

To locate the log file of user build output, identify the log file's path first. In the editor, open the OUTPUT tab by clicking View > Output: and the tab will appear at the bottom of the editor. Then, select IBM User Build from the dropdown menu.

The first line of the IBM User Build output will read “This log file is available at”, followed by a path. The output is similar to the following example:

This log file is available at c:\Users\userid\AppData\Roaming\Code\logs\20210610T094319\exthost1\IBM.zopeneditor\userbuild-20210610-164534.log

To access the log file, navigate to that path on your computer.

Note: The path to the log file might be hidden. In that case, adjust your operating system’s view preferences to show hidden items.

IBM Developer for z/OS on Cloud

For IBM Developer for z/OS on Cloud, to locate the log file of user build output, identify the log file's path first. In the editor, open the OUTPUT tab by clicking View > Output: and the tab will appear at the bottom of the editor. Then, select IBM User Build from the dropdown menu. The output is similar to the following example:

This log file is available at /home/wazi/.theia/logs/20210616T154415/host/ibm.zopeneditor/userbuild-20210616-154429.log

To locate and open the log using the path, you have to use the terminal in IBM Developer for z/OS on Cloud. First, click Terminal > Open Terminal in specific container and select the wazi-plugins container to create a new terminal.

Then, use the path found in the user build output tab to open the log in a default terminal editor. For example, run the commands, replacing the path and log file name with your user build output tab path details:

cd /home/wazi/.theia/logs/20210616T154415/host/ibm.zopeneditor/

vi userbuild-20210616-154429.log

Then type :q and hit enter to quit without saving any changes to the log.