Configure 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 example, 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. 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 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, such as include files defined in the ZAPP file of one workspace being used by program files in another. See the details in the respective sections.

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 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 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-3.0.0/resources/zapp-schema-1.0.0.json": [
    "zapp.yaml"
  ]
},
"json.schemas": [
  {
    "fileMatch": [
      "/zapp.json"
    ],
    "url": "file:///Users/user1/.vscode/extensions/ibm.zopeneditor-3.0.0/resources/zapp-schema-1.0.0.json"
  }
]

You are now ready to create your first ZAPP file.

Precedence of configuration settings sets

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 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 that contains a ZAPP file at

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

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 four property groups, one for each of the four 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 a profile of the type dbb.

profiles:
  - name: dbb-userbuild
    type: dbb
    settings:
      application: SAM
      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 ${application}"
        - "--hlq ${zopeneditor.userbuild.userSettings.dbbHlq}"
        - "--outDir ${zopeneditor.userbuild.userSettings.dbbLogDir}"
        - "--dependencyFile ${dependencyFile}"
      additionalDependencies:
        - application-conf
        - "zapp*"
      logFilePatterns:
        - "${buildFile.basename}.log"
        - "BuildReport.*"

The details for these profiles for User Build are documented in the IBM Knowledge Center pages for User Buildopen in new window.

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 entires 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 editor 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 as follows.

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

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 buildopen in new window. 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.
Last Updated:
Contributors: Peter Haumer, Lauren Li, Peter Haumer, kmaselli, Bradley Knaysi, Greg Lambert, Kimberlee Maselli, Lauren Li, shikunli