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
Verify the
copybookRule
setting in theapplication.properties
file.Open the
application.properties
file in theapplication-conf
folder in the VS Code workspace.Search on
copybookRule
and verify the USS location.The default USS location is as follows:
{"sourceDir": "${workspace}", "directory": "${application}/copybook"}
The user build functionality creates USS folders that align with the VS Code workspace subfolders. For example, if your workspace copybook folder is
zopeneditor-sample/COPYBOOK
, then the USS folder location will also be underzopeneditor-sample/COPYBOOK
. Therefore, the USS location in thecopybookRule
needs to match the USS 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
Verify the
plincRule
setting in theapplication.properties
file.Open the
application.properties
file in theapplication-conf
folder in the VS Code workspace.Search on
plincRule
and verify the USS location.The default USS location is as follows:
{"sourceDir": "${workspace}", "directory": "${application}/plinc"}
The user build functionality creates USS folders that align with the VS Code workspace subfolders. For example, if your workspace include folder is
zopeneditor-sample/INCLUDES
, then the USS folder location will also be underzopeneditor-sample/INCLUDES
. Therefore, the USS location in theplincRule
needs to match the USS 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 buildPSAM2.pli
in order for the linkedit step to complete successfully.
Verify settings for HLASM programs
Verify the
asmCopyRule
setting in theapplication.properties
file.Open the
application.properties
file in theapplication-conf
folder in the VS Code workspace.Search on
asmCopyRule
and verify the USS location.The default USS location is as follows:
{"sourceDir": "${workspace}", "directory": "${application}/asmcopy"}
The user build functionality creates USS folders that align with the VS Code workspace subfolders. For example, if your workspace copybook and macro folder is
zopeneditor-sample/ASMCOPY
, then the USS folder location will also be underzopeneditor-sample/ASMCOPY
. Therefore, the USS location in theasmCopyRule
needs to match the USS location generated during the user build process. In this example, the value should be:{"sourceDir": "${workspace}", "directory": "${application}/ASMCOPY"}
2. Running a user build
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 USS locations. You need to run this task only once unless other additional dependencies are needed later.There are two options for running a user build.
Run IBM User Build with full upload
- Upload all local copybooks referenced in the program. Use this option when you need to reupload all of the local copybooks to the USS application folder.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 USS 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 USS 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 uss 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
Wazi Developer for 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.
Wazi Developer for Workspaces
For Wazi Developer for Workspaces, 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 Wazi Developer for Workspaces. 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.