Setting up the user build

1. Starting from IBM® Wazi Developer 1.1.0, the user build functionality is part of the IBM Z® Open Editor VS Code extension. Install the IBM Z Open Editor VS Code extension and set property groups to ensure that copybooks can be resolved. To test whether a copybook can be resolved, open a COBOL program in the editor and move your mouse cursor over the copybook name in a COPY statement. If a copybook preview appears, it means that copybook is resolved successfully.

   For more information, see Setting preferences for code editing and Setting property groups.

2. Install Zowe™ CLI. To install Zowe CLI, see the Installing Zowe CLI section in topic Setting up integrations.

3. (Optional) If you plan to use RSE API to connect to USS, install IBM RSE API Plug-in for Zowe CLI. If you plan to use z/OSMF to connect to USS, you can skip this step. To install RSE CLI plug-in, see the Installing IBM RSE API Plug-in for Zowe CLI section in topic Setting up integrations.

4. Open the Terminal window in VS Code to create a Zowe CLI profile. Depending on how you are connected to the host, use one of the following commands:

   To create a z/OSMF profile:

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

   Learn more about creating z/OSMF profile.

   To create an RSE profile:

   zowe profiles create rse <profilename> --host <hostname> --port <portnum> --user <userid> --pass <pw> --base-path rseapi --protocol https --reject-unauthorized false

   Learn more about creating RSE profiles.

5. For z/OSMF only: In the Terminal window, create an SSH profile with the following command:

   zowe profiles create ssh-profile <profilename> --host <hostname> --port <portnum> --user <userid> --password <pw>

zAppBuild is the generic build solution for building z/OS® applications that uses Apache Groovy build scripts and DBB APIs. You can refer to zAppBuild as part of your DevOps transformation. The user build tutorial also uses the zAppBuild build solution to run the build.

If your USS system does not yet have the ~/dbb-zappbuild folder, you can clone it from the zAppBuild's GitHub repository and find instructions on setting up the appropriate properties files. Copy the dbb-zappbuild folder to your USS system.

Important: Make sure dbb-zappbuild/build-conf/datasets.properties is configured before user build is run. Refer to documentation above for details.

In order to specify the encoding with which files get uploaded to USS during user build, update the .gitattributes file located at the root of the repository. Entries in .gitattributes follow the format below:

pattern attr1 attr2 ...

• pattern describes the files to which the attributes attr1 and attr2 should be assigned. pattern follows fnmatch(3) glob style patterns.

• The attribute for configuring encoding on USS is: zos-working-tree-encoding

The following example specifies an encoding of IBM-1047 for all files in the repository with the .cpy file extension:

*.cpy zos-working-tree-encoding=ibm-1047

Learn more about gitattributes.

1. Access the User settings. User Settings are unique to each developer.

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

2. On the left side, navigate to the Extensions view, and click on IBM Z Open Editor. Alternatively, open the Settings page, use the search bar at the top on the page to search for IBM Z Open Editor, and scroll until you find Userbuild: User Settings.

3. Add the following User settings with your own information:

   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	Required parameter for IBM Wazi Developer for Workspaces. Optional parameter if you develop with IBM Wazi Developer for VS Code. VS Code will automatically determine your 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.	/Users/user/zopeneditor-sample

4. (Optional) Specify which Zowe CLI profiles should be used for User Build. If these are not defined, then the build process will search for default profiles 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 IBM Z Open Editor. Scroll down to the Zowe section and add the following profiles with your own information:

   Item	Value
   defaultCliProfile	The name of a valid RSE API or z/OSMF Zowe CLI profile created for the current user.
   defaultSshCliProfile	The name of a valid SSH profile created for the current user. Required for z/OSMF only.

   Note: To view the above settings in the JSON text format click the Open Settings (JSON) button located in the upper right corner of the page.

   View VS Code documentation for more details.

1. Copy and customize the following configuration into the .vscode/settings.json file.

   Notes:

   • Variable substitution is supported inside Workspace Settings when you set up for user build. The User Settings you defined in the previous steps will be substituted between the brackets ${} in Workspace Settings.

   • Optionally, you can paste your User Settings directly in .vscode/settings.json file so that they are all in one place.

   • The --dependencyFile argument is only supported for PL/I and COBOL based user builds.

   "zopeneditor.userbuild.workspaceSettings": {
       "dbb": {
         "command": "$DBB_HOME/bin/groovyz",
         "buildScriptPath" : "yourpath/build.groovy",
         "buildScriptArgs": [
           "--userBuild",
           "--workspace ${zopeneditor.userbuild.userSettings.dbbWorkspace}",
           "--application applicationName",
           "--hlq ${zopeneditor.userbuild.userSettings.dbbHlq}",
           "--outDir ${zopeneditor.userbuild.userSettings.dbbLogDir}",
           "--dependencyFile ${dependencyFile}"
         ],
         "additionalDependencies": [
           "application-conf"
         ]
       }
     },

   Update the following fields with your own information:

   • command: Points to the binary executable file that initiates the user build. For example, /bin/groovyz.

   • buildScriptPath: USS location of your dbb-zappbuild/build.groovy file or another build script file.

   • buildScriptArgs:

     • --userBuild - Indicates to DBB that this is a user build

     • --workspace - This setting is the parent workspace used by DBB and will be resolved by the value in the User Settings dbbWorkspace (see below)

     • --application - Name of the application to build. It must match your local VS Code workspace name as local application folder structure will be copied to z/OS. For example, if you're building our sample repo called zopeneditor-sample, the name of the application would be zopeneditor-sample.

     • --hlq - This setting is the TSO high-level qualifier(s) which is used by DBB for data set creation/updating and will be resolved by the value in the User Setting dbbHlq (see below).

     • --outDir - USS location for the log files and a subfolder to the workspace location.

     • --dependencyFile - Path to a dependency file on z/OS. The file will contain the list of copybooks and the type of application. If the default parameter ${dependencyFile} is used, user build will automatically generate and place this file in the dbbLogs folder location specified. Otherwise, you can specify the path to a file that already exists on z/OS.

     You can add additional arguments if needed. Refer to Command Line Options Summary for a complete list of optional arguments.

   • additionalDependencies - Other folders or files that are needed for the build, such as the application-conf folder containing the DBB properties files. The link can be either relative to VS Code workspace or absolute.

For more information about running a user build, see Building COBOL, PL/I, and HLASM programs with user build.