Set up and running an HLASM user build

Verify the maclibRule 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 maclibRule and verify the z/OS UNIX System Services location.
  
  The default z/OS UNIX System Services location is as follows:
```
{"sourceDir": "${workspace}", "directory": "${application}/maclib"}
```
IBM® User Build 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 maclibRule 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"}
```
Now, select a local HLASM program from your workspace to open in the editor and make changes.

After you complete and save your code changes, you can now run 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 z/OS UNIX System Services locations. This will only need to run once unless other additional dependencies are needed later. You can verify the files by using the Zowe™ tree viewer.
There are two options for running a user build.
- Run IBM User Build with full upload - this option will upload all local copybooks/macros referenced in the program. It would be used anytime you need to re-upload all of the local copybooks/macros to the z/OS UNIX System Services application folder.
- Run IBM User Build - this option will upload only those copybooks/macros that have been modified since the last upload, or any new copybooks/macros introduced into the program. This option will be used most often and will be the most efficient since it will not upload all copybooks/macros.
Option 1 - Select Run IBM User Build with full upload. This process determines the copybook/macro dependencies and uploads all local ones along with the HLASM 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/macros, it should only be used when it is necessary to actually upload all of the copybooks/macros. The HLASM program and copybooks/macros being uploaded will be listed in the output console window as seen here:
```
  =====================
  Running user build...
  Identified local root workspace path as c:\Users\userid\zopeneditor-sample
  Uploading c:\Users\userid\zopeneditor-sample\ASM\ASAM1.asm program.
  Found total of 1 local copybooks.
  Updating 1/1 local copybooks.
  Uploading c:\Users\userid\zopeneditor-sample\ASMCOPY\REGISTRS.cpy
```
Option 2 - Select Run IBM User Build. This process determines which copybooks/macros have been modified or are new since the last build and will only upload modified and new copybooks/macros with the HLASM file to the z/OS UNIX System Services file system. It then executes the DBB build script. The HLASM program and copybooks/macros being uploaded will be listed in the output console window as seen here:
```
  =====================
  Running user build...
  Identified local root workspace path as c:\Users\userid\zopeneditor-sample
  Uploading c:\Users\userid\zopeneditor-sample\ASMCOPY\REGISTRS.cpy program.
  Found total of 1 local copybook.
  Checking if copybook files were updated since last build...
  Updating 0/1 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/zopeneditor-sample/logs
Downloading logs to c:\Users\userid\zopeneditor-sample\logs
Downloading log file /u/userid/projects/zopeneditor-sample/logs/buildList.txt. Binary: false
Downloading log file /u/userid/projects/zopeneditor-sample/logs/BuildReport.html. Binary: true
Downloading log file /u/userid/projects/zopeneditor-sample/logs/BuildReport.json. Binary: true
Downloading log file /u/userid/projects/zopeneditor-sample/logs/ASAM1.log. Binary: false
Downloading of 4 log files to c:\Users\userid\zopeneditor-sample\logs finished successfully.

IBM User Build 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
...

Troubleshooting