Experimental: Configure your applications with ZAPP files

Using ZAPP (Z APPlication) files, which are independent of Visual Studio Code, is a new experimental approach for simplifying how developers and teams of developers can configure their application code for editing in IBM Z® Open Editor. As you have seen in Setting property groups, configuration settings such as property groups had to be entered as either VS Code user or workspace settings, despite being focused on describing the structure of your enterprise application. In essence, these configuration settings are actually independent of the VS Code editor. This makes it possible for 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.

Therefore, we created the new notion of a ZAPP file that describes your application in an independent representation, such as a YAML or JSON file, that can be managed with your source code, and that can be read by various editors and command-line tools in the future. 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 our IBM Knowledge Centeropen in new window).

Getting started with ZAPP files

Create a ZAPP file in your development workspace, that is, the top-level 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 also contains your .vscode directory in which your workspace settings can be stored, which was also the home previously for property groups and user build settings that now can be stored in ZAPP files instead.

Note: This current version of ZAPP supports only single-root VS Code and Eclipse Che/Red Hat® CodeReady Workspaces workspaces.

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.

  • zapp.yaml
  • zapp.json

If you decide to use YAML, which is the recommended format, you are suggested to install the Red Hat YAML VS Code Extensionopen in new window. 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 zcodeformat files is YAML and not Ansible.

In addition, code snippets for ZAPP in YAML is supported, which makes you productive instantaneously. If you use JSON, the default VS Code JSON editor also provides code completion and formatting, but currently no 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 zcodeformat 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 the zcodeformat schema.

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

You are now ready to create your first ZAPP file.

Precedence of configuration settings sets

Note: Because this is an experimental new feature, the previous ways of specifying the contents of a ZAPP file in user and workspace settings are still valid and all the settings you have created with previous versions of Z Open Editor can still be used. However, you cannot mix and match settings in different places.

Z Open Editor searches for property groups and user build settings in the following order and uses only the first set it finds:

  1. zapp.yaml in the workspace directory.
  2. zapp.json in the workspace directory.
  3. .vscode/settings.json in the workspace directory, which is the VS Code Workspace Setting you enter via the Preferences menu.
  4. Your user settings that you enter via the Preferences menu, which are stored in a different user-specific locationopen in new window depending on your operating system.

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 can load multiple zapp files located in the top-dir of each workspace. We search for property groups in each of these zapp files in a random order and try to resolve files. We recommend to use only one zapp file at the moment.
  • There can only be one zapp file in the multi-root workspace that needs to be located in the root of the same workspace as the program being built. The application-conf files (additional files listed in zapp profile) also need to be in the root of the workspace with the program. The rationale is that both are specific to the application/program being build.
  • For User Build copybooks can be located in any other workspace in the multi-root workspace. They can be in sub-folders. The zapp file in the application workspace specifies a relative path of the copybook to the other copybooks' workspace location (not relative to the app workspace location!).

See our Sample GitHub repositoryopen in new window 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 at

https://github.com/IBM/zopeneditor-sampleopen in new window.

This repository contains the following settings files so you can try all the variants and decide which works best for you:

  • A zapp.yaml file
  • A zapp.json file
  • The legacy workspace settings

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.json file, you must first delete or rename the zapp.yaml file.

Property Groups example

The zapp.yaml file contains the following content:

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

property-groups:
  - name: cobol-local
    language: cobol
    type: local
    syslib:
      - "**/COPYBOOK"
    libraries:
      - name: MYFILE
        locations:
          - "**/COPYLIB"
  - name: pl1-local
    language: pl1
    compilerOptions: not(!)
    type: local
    syslib:
      - "**/INCLUDES"
  - name: hlasm-local
    language: hlasm
    type: local
    syslib:
      - "**/ASMCOPY"
  - name: zowe-mvs
    type: mvs
    system: zos1000.example.com
    syslib:
      - USER1.SAMPLE.COBCOPY
    libraries:
      - name: MYLIB
        locations:
          - USER1.SAMPLE.COPY

This simple example defines four property groups. The first three are of the type local and define the location for include files for the zopeneditor-sample project for each language. The properties that are defined for each property group are spelled exactly the same as documented for workspace/user settings and listed in the property groups reference page for completeness.

The difference is that these property groups are now not mixed in with your editor settings and can be edited much more efficiently in YAML.

RSE Mappings example

At the end of the zapp.yaml file you find the example for the RSE Mapping that was shown and 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.

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 a profile of the type dbb.

profiles:
  - name: dbb-userbuild
    type: dbb
    settings:
      command: "$DBB_HOME/bin/groovyz -DBB_PERSONAL_DAEMON"
      buildScriptPath: "${zopeneditor.userbuild.userSettings.dbbWorkspace}/dbb-zappbuild/build.groovy"
      buildScriptArgs:
        - "--userBuild"
        - "--workspace ${zopeneditor.userbuild.userSettings.dbbWorkspace}"
        - "--application ."
        - "--hlq ${zopeneditor.userbuild.userSettings.dbbHlq}"
        - "--outDir ${zopeneditor.userbuild.userSettings.dbbLogDir}"
        - "--dependencyFile ${dependencyFile}"
      additionalDependencies:
        - application-conf

The properties map exactly to the settings documented for User Build in the IBM Knowledge Center pages for User Buildopen in new window. If you compare the JSON example provided there you see that the ZAPP notation has been exactly mapped to YAML.

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 type: mvs (around line 34) and press Enter to start a new line.
  2. Press Ctrl+Space to open up the code completion drop-down.

It then shows two properties that could still be added here: language and compilerOptions, which are not specified by this remote mvs property group yet.

Editing the zapp.yaml file with property group code snippets

ZAPP also provides code snippets so that you can enter new property groups rapidly as follows.

  1. Place your cursor at the empty line at the end of the file.
  2. Press Ctrl+Space again, 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 groups, add another syslib 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 syslib entry required 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 a local and a remote property group. You can then modify as needed.

In addition to using Ctrl+Space, you can also insert snippets via the VS Code Snippet Gallery that you can reach by following the steps below:

  1. Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows).
  2. Select Insert Snippet from the drop-down. You can type snippet to narrow down the list.

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 extensionopen in new window 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.

Converting your existing property groups to ZAPP files

If you have used property groups with previous versions of Z Open Editor and would like to convert them to ZAPP, then you can do that in one or two simple steps.

  1. Copy your property groups into a zapp.json file.
  2. (Optional) Convert the zapp.json to zapp.yaml.

Here are the steps in detail:

  1. Create an empty zapp.json file with an empty object { }.

  2. Use code completion in the JSON file to enter some required and optional properties such as name, version, and author.

  3. Open your VS Code workspace or user settings file in which you had previously stored your property groups.

  4. Cut the entire property groups entry from the settings file and paste it inside the object of your zapp.json. The result should look similar to the JSON object below:

    {
      "name": "sam",
      "zopeneditor.propertygroups": [
        {
          "name": "SAM-Copybooks",
          "type": "local",
          "syslib": ["**/COPYBOOK", "**/INCLUDES", "**/ASMCOPY", "**/REXXINC"]
        }
      ]
    }
    
  5. Change "zopeneditor.propertygroups" to "property-groups".

  6. Format the file by pressing Shift+Option+F (Mac) or Shift+Alt+F (Windows).

  7. Test whether your include files get resolved.

The resulting file looks as follows:

{
  "name": "sam",
  "property-groups": [
    {
      "name": "SAM-Copybooks",
      "type": "local",
      "syslib": ["**/COPYBOOK", "**/INCLUDES", "**/ASMCOPY", "**/REXXINC"]
    }
  ]
}

You can easily convert a valid zapp.json file to a zapp.yaml file by using another third-party VS Code Extension as follows.

  1. Install a VS Code Extension that can do such conversion; for example, YAML+JSONopen in new window.
  2. With this extension, you can now right-click the zapp.json files and select Convert to YAML.
  3. Rename the resulting file from zapp.yml to zapp.yaml.
  4. Test whether property groups are resolving correctly.
Last Updated:
Contributors: Peter Haumer, Lauren Li, Peter Haumer, kmaselli, Bradley Knaysi, shikunli, Greg Lambert, Kimberlee Maselli, Lauren Li