Experimental: Configure your applications with ZAPP files

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

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

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 Z Open Editor has started up.

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

You are now ready to create your first ZAPP file.

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 location depending on your operating system.

You can get started with ZAPP by cloning our sample GitHub repository at

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

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

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.

The zapp.yaml file contains the following content:

name: sam
description: Wazi's code samples with COBOL, PL/I, and HLASM applications
version: 1.1.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.

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.

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.

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.

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.

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"]
       }
     ]
   }

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"]
    }
  ]
}

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

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.