Configuring your applications with ZAPP files

Using ZAPP (Z APPlication) files is a new approach for simplifying how developers and teams of developers can configure their application code for editing in IBM Z® Open Editor. As VS Code settings only provide limited support for editing highly structured data, typing JSON structures is highly error prone, as well as users in the past got easily confused managing the many settings for all the extensions installed into VS Code all in one central place, we decided to introduce a new configuration file specifically for z/OS Enterprise applications.

We created the new notion of a ZAPP file that describes your application in an independent representation, as YAML files as well as alternatively JSON. This file can be managed with your source code in an SCM and can be used by various editors and command-line tools in the future. This makes it possible for common, application specific configuration settings, such as property groups, to be reused outside of VS Code and used with other editors or IDEs, as well as even for command-line operations for building your programs and other similar use cases. The vision is for ZAPP files to become as useful for z/OS® Enterprise Applications as Maven POM (Project Object Models) are for Java™ or package.json files are for Node.js.

Although this early version of ZAPP supports only a few Z Open Editor use cases, we are hoping that with feedback from the user community, we can evolve them over time by adding more specification items, supporting more tools, adding a command-line interface, and so on. Then, at some point we would like to provide extensibility APIs and open specifications that others can use to contribute to ZAPP as well.

ZAPP use cases

This early version of ZAPP is intended to provide a first impression to some of the ideas and to gather feedback. ZAPP files can currently be used to specify the following configurations:

• Property Groups for finding local or remote include files providing a complete alternative to settings described in the section Setting property groups.
• Property Groups for defining language-specific compiler options that impact how the IBM® language servers interpret source code.
• Code pages mappings for RSE API defining mappings for file name patterns to how they should be uploaded to and downloaded from MVS, which is fully documented in the section MVS EBCDIC code pages and mappings files.
• User build for building your programs currently edited in Z Open Editor remotely with the IBM Dependency Based Build offering. (You can find detailed documentation for this feature in IBM Documentation).
• Preprocessor support to specify command lines for executing a preprocessor in the background and integrating the output with the editor. See more details in Advanced Capabilities: Preprocessor support.
• Test case specification utilized by IBM's z/OS test automation tools portfolio.

Getting started with ZAPP files

When you open a COBOL, PL/I, HLASM, REXX, or JCL program for the first time from a VS Code workspace and you do not have a ZAPP file, Z Open Editor will automatically create a zapp.yaml file for you to specify a so-called property group that defines where include files can be found. The file will be located in the top-level folder of your workspace. If you are using multi-root workspaces, you can find it in your first workspace, as listed in your .code-workspace file. You can move the file to any other of your workspaces, but it must be located in the top-level folder. In case of multi-root workspaces, this file will instruct Z Open Editor to search all directories in all your workspaces for the include files. For very large workspaces, the searching can slow down the editor's performance. Therefore, you are encouraged to edit the file after its creation to narrow down the location of the include files as described in Setting property groups.

The top-level folder is the directory that typically contains your .git directory if you are using Git, and/or the top-level directory that you would open in VS Code with File > Open.... This directory typically contains your .vscode directory in which your workspace settings can be stored. Previously, this directory was also the home for property groups and user build settings that now need to be stored in ZAPP files instead. In case of a multi-root workspace setup, each workspace can have a ZAPP file and they can be used in combination with each other; for example, the include files defined in the ZAPP file of one workspace can be used by program files in another. See the details in the respective sections.

You can disable the automatic creation of the ZAPP file by setting zopeneditor.zapp.generateZappOnDemand to false. You can manually create a ZAPP file in your development workspace by going to File > New Text File.

You can choose to edit your ZAPP file as a YAML file or as a JSON file and create a file with either of the following names in your top-level directory. The file must be named exactly like that to enable YAML or JSON editors to recognize the schema to be used for validation.

• zapp.yaml
• zapp.json

If you decide to use YAML, which is the recommended format as it easier to write than JSON, you are suggested to install the Red Hat YAML VS Code Extension. This VS Code extension provides code completion, documentation, and formatting features, which are useful for ZAPP. Z Open Editor can recognize the installation of the Red Hat YAML extension automatically and configure the ZAPP schema for this extension in your VS Code user settings. Note, if you also have the Red Hat Ansible VS Code extension installed make sure that the language selected in VS Code for the ZAPP files is YAML and not Ansible, as both use the file extensions .yml and .yaml and you have tell the editor, which language is being edited.

In addition, code snippets for ZAPP in YAML are provided, which makes you productive instantaneously. If you use JSON, the default VS Code JSON editor also provides code completion and formatting, but currently there are no snippets included in Z Open Editor. However, you could create your own custom snippets.

When Z Open Editor starts up it checks if the Red Hat YAML extension is installed. If it is, the editor will add links to the ZAPP JSON schema that is used for the YAML editor for validation automatically. If this extension is not installed, Z Open Editor will only add a schema link to the JSON editor. To verify that Z Open Editor has configured itself to work with the Red Hat YAML extension or VS Code JSON, look for entries as shown below in your VS Code user settings. The entries should be added after opening Z Open Editor. There might be other schema entries listed here such as the links to Z Open Editor's zcodeformat schema or schemata used by third party extensions.

"yaml.schemas": {
  "file:///Users/user1/.vscode/extensions/ibm.zopeneditor-5.0.0/resources/zapp-schema-1.3.0.json": [
    "zapp.yaml"
  ]
},
"json.schemas": [
  {
    "fileMatch": [
      "/zapp.json"
    ],
    "url": "file:///Users/user1/.vscode/extensions/ibm.zopeneditor-5.0.0/resources/zapp-schema-1.3.0.json"
  }
]

You are now ready to create your first ZAPP file.

Configure ZAPP files with user setting variables

ZAPP files support variable substitution. You can define variables inside VS Code settings and use those variables inside a ZAPP file. This is useful when a ZAPP file is shared in a repository and users need to make personal adjustments to it without modifying the original ZAPP file.

To define ZAPP user variables, open your VS Code user or workspace settings and specify names with values under zopeneditor.zapp.variables. You can do this in the graphical editor using a table. Search for "zapp" to quickly find it and click Add Item to insert a new row for your variable. Alternatively, you can add and edit variables in the JSON representation of the settings as shown in the following example:

  "zopeneditor.zapp.variables": {
    "PERSONAL_DIR": "/Users/user1/copybooks",
    "USER": "IBMUSER",
  }

To reference ZAPP variables, write ${variable-name} in your ZAPP file. For example:

  - name: cobol-copybooks
    language: cobol
    libraries:
      - name: syslib
        type: local
        locations:
          - "**/${PERSONAL_DIR}"
      - name: syslib
        type: mvs
        locations:
          - "${USER}.SAMPLE.COPY"

Note that all users need to define all the variables in their user settings that are used by the ZAPP file to avoid errors. Do not use single or double-quote characters for variable names and values. You can place these properties in VS Code user as well as workspace settings.

Precedence of zapp files

Within a workspace Z Open Editor searches for ZAPP files in the following order and uses only the first one it finds:

1. zapp.yaml in the workspace directory.
2. zapp.json in the workspace directory.

Single-root versus multi-root workspaces

There is limited support for ZAPP files for multi-root workspaces with these rules:

• Property Groups: the multi-root workspace loads all the zapp files located in the top-directory of each workspace. Z Open Editor will use all the property groups defined in these ZAPP files in the order of the workspaces as they were defined in the multi-root workspace's .code-workspace file. You can manually edit this file to change the order. This order is also the order in which workspaces are presented in VS Code's Files Explorer. So property groups are used top to bottom.
• Dependency Based User Build: For the program being built the ZAPP file that is located at the root of the same workspace in which the program is located is being used for the DBB profile to be used. All the location specified in that DBB profile for additional dependencies, such as application-conf files, need to be in the same workspace as the program. Include files such as copybooks can be located in any other workspace as they are searched in all available property groups as defined in the previous bullet point.

See our Sample GitHub repository for more details and examples for single-root workspaces, in the wazi-main branch as well as multi-root in the multiroot folder of the wazi-main branch.

A ZAPP file example

You can get started with ZAPP by cloning our sample GitHub repository that contains a ZAPP file at

https://github.com/IBM/zopeneditor-sample.

This repository contains the following settings files so you can try it with YAML or JSON and decide which works best for you:

• A zapp.yaml file
• A zapp-example.json file

There are two different version of these files in the branches main and wazi-main. If you are using other IBM Wazi capabilities such as IBM User Build switch to the wazi-main branch instead.

Note: According to the precedence rules stated in the previous section, if you want to try the zapp-example.json file, you must first delete or rename the zapp.yaml file and then rename it to zapp.json.

Property Groups example

The zapp.yaml file contains the following:

name: sam
description: Wazi's code samples with COBOL, PL/I, HLASM, and REXX applications
version: 3.0.0
author:
  name: IBM CORPORATION

propertyGroups:
  - name: cobol-copybooks
    language: cobol
    libraries:
      - name: syslib
        type: local
        locations:
          - "**/COPYBOOK"
      - name: syslib
        type: mvs
        locations:
          - "IBMUSER.SAMPLE.COBCOPY"
      - name: MYLIB
        type: mvs
        locations:
          - IBMUSER.SAMPLE.COPYLIB
      - name: MYLIB
        type: local
        locations:
          - "**/COPYLIB-MVS"
      - name: MYFILE
        type: local
        locations:
          - "**/COPYLIB"

If you look further in the file it defines five property groups, one for each of the five languages supported by Z Open Editor. The first, shown above, is for the COBOL samples in this Git repository. See the details for property groups in Setting property groups.

RSE Mappings example

At the end of the zapp.yaml file you also find an example for an RSE Mapping that is documented in MVS EBCDIC code pages and mappings files. You can see that is was listed as an entry of the type rseapi in the profiles section, which indicates an extension to the ZAPP core properties that are defined for special and optional tool capabilities such RSE API or User Build.

profiles:
  - name: RSE-Mappings
    type: rseapi
    settings:
      mappings:
        - resource: "**.SAMPLE.COB**"
          extension: cbl
          transfer: text
          encoding: IBM-037
          memberMappings:
            - extension: dat
              transfer: binary
              resource: "*DAT"
        - resource: "**PLI*"
          extension: pl1
          transfer: text
          encoding: IBM-037
      default.encoding: IBM-037

User Build profile example

If you are working in the wazi-main branch you will find in-between the property groups and the RSE mapping two profile entries of the type dbb. The first is an example for specifying a user build with IBM Dependency Based Build (DBB) version 3's new zBuilder. The second profile is an example, for how to use DBB version 2 (or newer) with Groovy build scripts provided by the zAppBuild Github repository.

Here is an example for a DBB v3 profile:

profiles:
  - name: zBuilder-userbuild
    type: dbb
    settings:
      command: "$DBB_HOME/bin/dbb build"
      lifecycle: user
      lifecycleArgs:
        - "--hlq ${zopeneditor.userbuild.userSettings.dbbHlq}"
      additionalDependencies:
        - "dbb-app.yaml"
      logFilePatterns:
        - "${buildFile.basename}-*.log"
        - "BuildReport.*"

The details for these profiles for User Build are documented in the Setting up the user build.

Editing the zapp.yaml file with code completion

Code completion requires that you have the Red Hat VS Code YAML extension installed and configured as outlined above. You can try it out as follows:

1. Place your cursor behind the line with language: cobol (around Line 18) and press Enter to start a new line.
2. Press Ctrl+Space to open up the code completion drop-down.

It then shows one property that was not yet used in this property group, compilerOptions, that could still be added here. You can add it by simply clicking the item or you the keyboard's arrow and return keys.

The same will also work with property values if they are enumeration types or boolean.

1. Move the cursor at the end of the line type: local (around Line 21).
2. Delete the word local and do another Ctrl+Space.

It now shows you the two allowed options local and mvs in the drop-down that you can choose from.

You also see in the drop-down various code snippets that could be inserted here. However, you see that properties are listed context-sensitive, i.e. the drop-down only shows entries that are allowed to be inserted here. Code snippets are not context sensitive and will always be displayed. You need to make sure you use them syntactically correct. The YAML editor extension will tell you with syntax errors when you insert incorrectly.

Editing the zapp.yaml file with property group code snippets

ZAPP also provides code snippets so that you can enter new property groups rapidly. The code snippets are only available in the code editor when you edit a zapp.yaml file. You will not find them in the VS Code Snippets gallery, because VS Code currently cannot distinguish between different YAML file types in their snippet gallery.

To use these code snippets:

1. Place your cursor at the empty line at the end of the property groups in the file (around Line 85).
2. Press Ctrl+Space and you will see four code snippets listed in the drop-down.
3. Navigate down and select ZAPP Remote MVS Property Groups by pressing the Enter key.
4. You can see that a new property group is inserted with highlighted placeholders.
5. Before clicking or typing anything else, while the placeholders are still highlighted, use the Tab and Shift+Tab keys to navigate between the placeholders and enter values for name, language (using another drop down), and syslib entries.
6. At the end of the new property group, add another locations entry by adding a new line and entering a new value such as - USER1.SAMPLE.INCLUDES.

Remember that you need to provide a valid YAML file. As the locations entry requires a string array in JSON, it now needs to be entered in YAML as an ordered list using - for each value.

There is also a code snippet template for a complete ZAPP file. You can try it out as follows:

1. In the current editor window for zapp.yaml, do a Select-All and delete all the contents of the file. You can withdraw the deletion later as the file is managed in Git.
2. In the first line and column of the empty document, press Ctrl+Space and select the ZAPP Template snippet. Instead of scrolling all the way to the bottom, you can type that snippet name instead.
3. You see that a snippet was inserted that contains general properties at the top as well as one property group with a local libraries entry. You can then modify as needed or add more property group entries using the respective snippets.

Editing the zapp.yaml file with User Build code snippets

You can specify all the workspace settings for a user build in ZAPP files as documented in Setting up the user build. User settings are still required to be stored in the VS Code user settings files in this release, but all workspace settings are available as tools profile in ZAPP.

You can find an example for a DBB profile at the end of the sample ZAPP file from the zopeneditor-sample GitHub repository. If you removed all content as mentioned in the previous section, you can create a tools profile yourself as follows:

1. Go to the end of your file behind the last property group to column 1.
2. Type the key word profiles: and press Enter.
3. As you can specify an ordered list of many profiles, start a new list by indenting and typing - followed by any of the properties proposed by the code completion.
4. When you select the mandatory type property, you can use a drop-down to select the type of the profile. Right now, only the type dbb is supported.
5. Once you selected the type dbb, you can add a settings: property, which defines an object of unordered properties that you can also enter after indentation with code completion.

Instead of entering a DBB profile all manually, you can also use a code snippet provided by Z Open Editor as follows:

1. In the column after the profiles: entry, press Ctrl+Space and select the ZAPP User Build Profile snippet.
2. The snippets contain a full DBB profile with placeholders. You can then navigate by pressing Tab and replace the placeholders with your specific values.

Reviewing syntax errors

When you create an invalid zapp.yaml file by typing incorrect YAML or misspelling property names, the Red Hat YAML extension will show you syntax errors in the Problems view. You can try it out as follows:

1. Remove a few letters from any of the properties to misspell it.
2. Switch to the VS Code Problems view. Use the View > Problems View menu if you do not see it. This view will now show you the exact syntax error as well as the line and column it happened in.

If you do not have the Red Hat YAML extension installed, you can still find simple error lists provided by Z Open Editor in the Output view as follows:

1. Switch to the Output view. Use the View > Output View menu if you do not see it.
2. On the right side of the Output view, select IBM Z Open Editor from the drop-down.
3. Make some syntax errors. Note that whereas the Red Hat extension will show you errors right away, here you will not see any errors until you attempt a save.
4. Save your file with the syntax error. Now the Output View will show you error messages such as should NOT have additional properties(additionalProperty:lauage).

As you can see, the output here is much simpler and does not have line numbers. The Red Hat extension is by far the superior solution for editing ZAPP files as that extension includes a full YAML Language Server that generates an Outline view.

Formatting your zapp.yaml file

Another capability of the Red Hat YAML extension is the ability to format your ZAPP file consistently. If you used different indentations in places, you can simply correct the formatting of the entire file by using one of the following two ways to format:

• Use the shortcut Shift+Option+F (Mac) or Shift+Alt+F (Windows).
• Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows), and type "format" to select Format Document.