Experimental: Formatting COBOL source code

IBM Z® Open Editor v2.1.0 or newer provides an experimental COBOL source code formatting feature that allows developers to reformat the source code of an entire file, or the currently selected portion of the file, using the VS Code formatting menus and shortcuts. The rules of formatting are determined by a set of common defaults that can be customized along many criteria. The customizations of the default formatting rules are represented in a YAML or JSON file that can be stored in a version control system with the actual source code, in order to ensure that all developers in a project perform formatting consistently.

The formatting customization files are called zcodeformat. They describe your structured formatting preferences defining only the changes you want to make to the defaults. The user experience working with these files was designed to be very consistent to how you work with ZAPP files in Z Open Editor, but kept separate as ZAPP focuses on application properties independent of the presentation of the code. Our vision is for zcodeformat files to become as useful for z/OS® Enterprise applications as formatting is with the popular Prettier tool that is available for many other languages.

Currently, this capability is only available for COBOL.

Formatting your COBOL files

To format your COBOL file (programs file or copybook) you can either

• format the full document via the right-click "Format Document" context menu option or via the shortcut Shift+Option+F (Mac) or Shift+Alt+F (Windows).
• format the currently selected text range via the right-click "Format Selection" context menu option or via the shortcut Command-K Command-F (Mac) or Ctrl-K Ctrl-F (Windows).

Getting started with zcodeformat files

Create a zcodeformat file in your development workspace, in the top-level directory that 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 where your workspace settings are stored.

Note: The current version of zcodeformat supports only single-root VS Code and Eclipse Che/RedHat® CodeReady Workspaces workspaces.

You can choose to edit your zcodeformat file as a YAML file or a JSON file, and create a file with either of the following names in your top-level directory. Only create one of these and name it exactly as shown below, using only lowercase characters.

• zcodeformat.yaml
• zcodeformat.json

If you decide to use YAML, which is the recommended format, installing the Red Hat VS Code Extension is also recommended. This VS Code Extension provides code completion, documentation and formatting features that are useful for zcodeformat. Z Open Editor automatically recognizes the Red Hat YAML extension installation and configures the zcodeformat schema for it 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.

Code snippets for zcodeformat in YAML are also available and help to immediately become productive. If you use JSON, the default VS Code JSON editor also provides code completion and formatting, but there is currently no support for code 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 for 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 ZAPP schema.

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

You are now ready to create your first zcodeformat file.

Precedence of formatting settings sets

Z Open Editor searches for formatting settings in the following order and uses only the first rule set it finds:

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

A zcodeformat file example

You can get started with zcodeformat 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 zcodeformat.yaml file
• A zcodeformat-example.json file

Note: Any property that is omitted within a zcodeformat file is set to a default value that can be found within the COBOL Code Formatter template with all indentation options code snippet.

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

COBOL example

The zcodeformat.yaml file contains the following content:

cobol:
  dataDivision:
    alignValueClauses: false
    indentation:
      indentLength: 1
  procedureDivision:
    indentation:
      indentForAllBlocks: 1
  commentCase: none
copybook:
  codeCase: upper

This simple example defines some custom preferences for the COBOL files contained in this sample repository that we chose to use for our files.

Copybook example

At the end of the zcodeformat.yaml file there is also an example for one of the supported copybook file options.

Editing the zcodeformat.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 curser behind the line with indentLength: 1 (around line 5) and press Enter to start a new line.
2. Press Ctrl+Space to open up the code completion drop-down.

It then shows the other property that could still be added here, startOfAreaA, which hasn't been specified by this zcodeformat file yet.

Editing the zcodeformat.yaml file with code snippets

The zcodeformat editor also provides a code snippet template for a complete zcodeformat file that you can use as a starting point. These code snippets are only available in the code editor when you edit a zcodeformat 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. In the current editor window for zcodeformat.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 COBOL Code Formatter template with all indentation options Template snippet. Instead of scrolling all the way to the bottom, type that snippet name instead.
3. You can see that a snippet was inserted that contains default values for COBOL and copybook formatting settings.

Reviewing syntax errors

When you create an invalid zcodeformat.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.
4. Save your file with the syntax error. (The Red Hat extension will not show any errors until you save the file.) Now the Output View will show you error messages such as should NOT have additional properties.

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 zcodeformat files as it includes a full YAML Language Server that generates an outline view.

Common syntax errors

There are some restrictions on certain dependent and conflicting properties within a zcodeformat file.

1. Any items within an indentation item are not allowed when the enableIndentation of the same level is set to false.

   cobol:
     dataDivision:
       enableIndentation: false
       indentation:
         startOfAreaA: 8
   

   In this case, startOfAreaA is not allowed because enableIndentation is false

2. If any items are used within cobol > procedureDivision > blocks, indentForAllBlocks is now allowed within cobol > procedureDivision.

   cobol:
     procedureDivision:
       enableIndentation:
       indentation:
         indentForAllBlocks: 5
         blocks:
           indentExecBlock: 5
   

   In this case, indentForAllBlocks is not allowed because indentExecBlocks is specified.

   Note: the indentForAllBlocks property is not allowed if any child properties underneath blocks are present.

Learning the schema

The built-in schema support of VS Code provides you with code completion and rich hovers that, together with the available code templates, allow you to learn the details behind the zcodeformat schema for writing these files. However, the formatter and schema is based on the code formatter available in IBM Developer for z/OS. See this documentation page a for a reference to learn how the different formatting options behave.

Formatting your zcodeformat.yaml file

Another capability of the Red Hat YAML extension is the ability to format your zcodeformat file consistently. For example, if you inadvertently used different indentations, you can simply correct the formatting of the entire file by using one of the following two formatting commands:

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