SuperBOL Studio OSS: A New Platform for COBOL

Visual Studio Code extension for COBOL.

Getting started

Installation

You can install SuperBOL Studio OSS either directly from within VS Code, or via a VSIX file.

Installation within VS Code

First, click on the "Extensions" icon in the activity bar on the left-hand side, or press Ctrl+Shift+X. Then, type "superbol" into the search bar to find it, and press its Install button.

You can find further instructions for installing extensions directly within VS Code on this page.

Installation via a VSIX file

First, download a VSIX file from the Marketplace or Open VSX.

To install the extension from its VSIX file, open VS Code and go to the the "Extensions" view. In the sidebar, click on the three dots (⋅⋅⋅) on the top right-hand side (just above search), select Install from VSIX…. Pick the VSIX file you just downloaded to install it.

Editing an existing project

To start using the extension on an existing project, open its folder in VS Code (File > Add Folder to Workspace…). The extension will start automatically whenever the folder contains files with usual COBOL filename extensions (.cob, .cbl, .cpy, .cbx).

Then, open the settings (File > Preferences > Settings, or Ctrl+,), and start typing "superbol…". You will be presented with a screen that resembles:

From here, you can notably configure:

• The COBOL dialect used in the project (see here for a documentation on every available dialect). In SuperBOL, the default dialect corresponds to GnuCOBOL's default, that supports many features from dialects such as COBOL2014, IBM, Micro Focus (mf), or GCOS for instance;

• The default reference source-format (see here for a documentation on the supported source formats). When auto is selected, which is the default, SuperBOL (and GnuCOBOL) will automagically try to guess whether the source is in free or fixed format. Other source formats need to be configured explicitly.

• The path to copybooks. To configure this setting, you will need to select Edit in settings.json. This is a list, where each entry describes an element of the search path where your copybooks will be looked for. Each entry must contain a directory name dir, and may feature an optional file-relative flag. When absent or set to false, the latter field indicates that the directory name is either absolute, or relative to the root of the project's directory. When file-relative is true, the element of the search path is considered relative to the directory where each main source program is located.

  

Syntax diagnostics

[!NOTE]

Syntax checks performed by SuperBOL Studio currently cover the COBOL85 dialect, and some constructions of more recent dialects supported by GnuCOBOL. Reporting of such diagnostics is currently disabled for dialects other than COBOL85 to avoid misleading developers with false diagnostics about syntax errors.

Reporting can be re-enabled for every dialect by setting the Force Syntax Diagnostics flag in SuperBOL configuration settings.

Navigation features

Go to Definition

When you want to locate the definition of a data item name in your source code, position your cursor on its name, right click, and select  Go to Definition (or press F12).

Peek Definition

To only have a peek at where such a data item defined, you can position the cursor on its name, right click, and select  Peek > Peek Definition (or press Ctrl+Shift+F10). You will then be presented with a view of the location of the corresponding definition, including if it lies in a copybook.

Go to References

If you want to obtain a list of all references to a named data item, right click and select  Go to References (or press Shift+F12). You will then view the location of every reference to this item.

[!NOTE] (Temporary limitation)

At the moment, definitions that belong to some sections of the data division, and some references to data items, are ignored by the extension. They will be covered by the first stable release.

Hover to Show Copybooks

Ever wondered what was behind a COPY directive? Just position your cursor over such a statement, and you will be presented with the contents of the copybook.

Hover to Show Source Text Replacements

What's more? You can see the source text that results from replacement by a REPLACE directive in the same way.

Debugging

In order to debug a COBOL program, you first need to run a build task with appropriate debug options. Once this is done, you can launch the compiled program in a debugging session.

[!NOTE]

We recommend that a version of GnuCOBOL that is at least as recent as version 3.2 be available on the system running VS Code. Debug and coverage features respectively assume that gdb and gcov are installed.

On Windows systems, users may employ dedicated installers that are available here. Linux users may rely on their favorite package manager and install gnucobol.

Running a Build Task for Debugging

After having opened the program to debug, select Terminal > Run Build Task… (Ctrl+Shift+B), and then SuperBOL: build (debug).

Launching the Compiled Program for Debugging

If needed, you can place a breakpoint on statements (or paragraph titles in the procedure division) by clicking on the red dot that appears when you hover the cursor on the left margin (or with F9). Click on the red dot or press F9 again to remove a breakpoint. Then, to launch the program in debug mode, select Run > Start Debugging (F5). This will run your program until a first breakpoint if reached, or to completion.

Once stopped on a breakpoint, you can investigate the values of data items from the program using the VARIABLES panel on the left-hand side.

Press F10 to step to the next statement, or F5 again to continue until the next breakpoint, or termination of the program.

Customizing Build Tasks

To customize a build task, you can select Terminal > Configure Default Build Task…, and then SuperBOL: build or SuperBOL: build (debug) (the latter being the task that is run whenever you start a debugging session, e.g with F5).

Save the tasks.json as shown. Definitions for this task notably include a for-debug flag, that instructs the compiler to insert debug annotations into generated executable files, as well as extra-args, that can be edited to pass additional arguments to the cobc compiler.

Coverage

GnuCOBOL can instrument your programs so they can generate coverage information at runtime. To enable this feature, you can set the for-coverage setting to true in the Superbol: build (debug) task in your tasks.json file (see Section Customizing Build Tasks).

Coverage Information

Generated coverage files are in gcov format; they are portable, and you can use them as you would any other coverage file generated for programs written using other programming languages.

Highlighting Coverage Information

Coverage data can be shown after the execution of a program that was compiled to generate this information terminates. SuperBOL will display coverage on a line-by-line basis, by highlighting the lines of your source code using colors that represent their coverage status. To enable coverage highlighting, you can open the command palette (or type Ctrl+Shift+P), and select SuperBOL: Show Coverage. You can also hide the highlighting with the command SuperBOL: Hide Coverage, and update it after re-executing your program with SuperBOL: Update Coverage.

Miscellaneous

Collaborating with other developers

At this point, the settings for your project are stored and managed by VS Code. However, you may plan to collaborate with developers that do not use this editor. For instance, they might want to use our mode for GNU/Emacs, which is located here. Then, we advise you to let SuperBOL Studio store the configuration in a superbol.toml file that will be located at the root of the project.

You can make the extension write your current project configuration into a superbol.toml by entering the command palette (View > Command Palette…, or press Ctrl+Shift+P), and then selecting the command SuperBOL: Write Project Configuration.

This will save a superbol.toml file at the root of each currently opened project directory. Such a file will not store any user-specific settings, so you can now safely put them under source control. Extensions dedicated to the edition of TOML files, such as tamasfe.even-better-toml, provide the same level of assistance as when you edit .vscode/settings.json.

[!TIP]

Install the OCamlPro.SuperBOL-studio-pack extension to get SuperBOL Studio OSS and tamasfe.even-better-toml altogether.

Further documentation

You can check further the documentation on using the extension on this page.

Mode for GNU/Emacs

You can find here a mode that allows you to use the SuperBOL LSP server with GNU/Emacs.

Using the SuperBOL LSP server with other editors

This page documents how to use our LSP server functionnality with other editors.

Building from sources

If you build from a clone of the git repository, make sure to update submodules:

git submodule update --init --recursive

You first need to install a few external dependencies to build the LSP server and the VSCode extension from sources.

1. First, you need to install and initialize opam;

2. Then you need a recent version[^drom-version] of our build tool drom. The easiest way to have it running is via the following command:

   opam pin add https://github.com/OCamlPro/drom.git

   [^drom-version]: Current version is 0.9.2~dev3 (commit 63a5770).

3. Install node.js (version >=5.2.0) if it is not already installed.

4. You can then install all remaining dependencies, and compile the LSP server along with the VS Code extension:

   make build-deps vsix-release

Resources

• Website: https://ocamlpro.github.io/superbol-studio-oss
• General Documentation: https://ocamlpro.github.io/superbol-studio-oss/sphinx
• Sources: https://github.com/ocamlpro/superbol-studio-oss