Micro Focus COBOL extension

The Micro Focus COBOL extension provides support for compiling, editing, and debugging COBOL source code in Visual Studio Code on Windows and Linux.

Read the full documentation for Micro Focus COBOL here

Features include:

Editing support for COBOL code - basic syntax colorization, source format and dialect recognition are available.
Compilation of COBOL code - supports the compiling of source files when either an Eclipse COBOL project or a Visual Studio COBOL solution file is present, or using custom build scripts.
Debugging of .NET Core COBOL code - offers breakpoints, variables, stepping through code.
Debugging of native COBOL code - offers debug configurations, breakpoints, watchpoints and program breakpoints, inline values of variables, debugging of applications running on a remote machine or in an Enterprise Server instance, and just-in-time debugging (JIT).

Note: Compile and debug features are available when a compatible version of Micro Focus Visual COBOL or Enterprise Developer is installed on the same machine. See the full documentation for details.

Visit the Micro Focus Community Forum for help with the extension and to discuss this product with other users and Micro Focus specialists. For help with functionality in the extension that relies on your licensed Micro Focus COBOL product, you can also contact Micro Focus Customer Care.

Verifying the Digital Signature

The .vsix package for this extension can be verified using a hosted digital signature. For more details, see Verifying the Digital Signature of a Micro Focus Extension for Visual Studio Code.

What's new in version 1.0.38

A Micro Focus COBOL Terminal is now provided.

What's new in version 1.0.36

The debugger now includes support for the memory view when debugging native code.
The extension settings includes an entry to allow a Consolidated Tracing Facility configuration file to be used when building and debugging.

What's new in version 1.0.34

Code snippets are available for COBOL code.

What's new in version 1.0.32

It is now possible to install this extension to edit COBOL files when you use Visual Studio Code in a Web browser.
When COBOL tab stops are enabled, backspace now removes all spaces up to the last COBOL tab stop.
Colorization has been improved within the Identification Division and EXEC blocks.
Colorization has been added for the ACUCOBOL Terminal source format.

What's new in version 1.0.29

Watchpoints and program breakpoints are now supported in native COBOL
Add and remove line comment commands are now supported for COBOL source files
Tab support in COBOL sources has been improved and supports COBOL tab stops
The values of variables are now shown inline in the editor while debugging

Editing Support

This extension supports editing Micro Focus COBOL and a range of mainframe COBOL dialects.

You can configure the editor with the following GUI settings:

Micro Focus COBOL: Dialect - the default dialect to apply to COBOL files. Set to "Micro Focus" by default.
Micro Focus COBOL: Source Format - the default source format to apply to COBOL files. Set to "fixed" by default.

You can also set your editor preference in the global Visual Studio Code configuration file, settings.json (in %userprofile%\AppData\Roaming\Code\User (Windows) or in ~/.config/Code/User (Linux)). Add the Micro Focus settings in the following format: ' "setting": "value" '. For example:

{
    "microFocusCOBOL.dialect": "Enterprise COBOL for z/OS",
    "microFocusCOBOL.sourceFormat": "fixed"
}

For example, to configure the source format and the COBOL dialect use:

microFocusCOBOL.sourceFormat: sets the default source format that is applied to COBOL documents for colorization
microFocusCOBOL.dialect: sets the default dialect that is applied to COBOL documents for colorization

To customize the colors of the COBOL words in the editor use editor.semanticTokenColorCustomizations the "rules" option, and with the settings prefixed "cobol". For example:

{
    "editor.semanticTokenColorCustomizations": {
        "enabled": true,
        "rules": {
            "cobol-identifier": "#3b8dda",
            "cobol-keyword": "#ff0000"
        }
    }
}

Where you can access the list of COBOL words whose color to modify if you start typing cobol-. You receive a list of suggestions to choose from.

Rulers for COBOL

The extension applies default rulers when you open a COBOL file in the editor which makes it easier to identify the COBOL areas and columns. You can configure these by changing the language defaults in the settings.json mechanism. For example, change the location of the rulers in the following section:

{
    "[cobol]": {
        "editor.rulers": [
            6,
            7,
            72
        ]
    }
}

Compiling Support

Visual Studio Code offers a number of build tasks that use the Micro Focus Visual COBOL or the Enterprise Developer Compiler to build your COBOL files. The build tasks are available from the Terminal menu.

Configuring Visual Studio Code for compiling

Compiling requires a licensed Micro Focus COBOL product. Specify the location of the product in the extension setting Micro Focus COBOL: Install Location. From the extension settings, specify any Ant and MSBuild settings as required.

Compiling using a Visual Studio project

Build tasks are available out-of-the box for compiling existing MSBuild COBOL projects (.cblproj) that have been created using either Visual COBOL or Enterprise Developer for Visual Studio. If the folder open in Visual Studio Code contains the .cblproj or the .sln file for your COBOL sources, the Run Build Task command will make these available. You can configure the build task using the tasks.json file as required.

Compiling using an Eclipse project file

You must install Ant and add it to the PATH environment variable before you can compile projects. A build task is available for compiling existing Eclipse COBOL projects (.cobolBuild) files that have been created using Visual COBOL or Enterprise Developer for Eclipse. If the folder opened in Visual Studio Code contains the .cobolBuild file, the extension automatically generates a task for compiling the project using Ant. You can optionally configure the generated build task.

Creating custom build tasks

Your COBOL sources might be using a custom build script to compile. In this case, we recommend defining a custom build task to invoke the build script. The extension includes a COBOL-shell task type that makes the required compilation tools such as cobol.exe (on Windows) and cob (on Linux) available to the build script. This requires the location of the installed COBOL product to be set in the extension settings.

See below an example COBOL build task that invokes a batch file. cobol.exe can then be used in the batch file to compile the COBOL sources.

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "My Cobol Build",
            "command": ".\\build.bat",
            "type": "COBOL-shell",
            "problemMatcher": [
                "$COBOLErrFormat3"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]
}

Using Problem Matchers

A problem matcher is a feature of Visual Studio Code. It scans the build output for error messages and converts them to errors that can be shown inside the editor or in the Problems panel. If you have any custom build tasks, you need to manually enable the suitable problem matchers for them. In order to integrate a problem matcher, add the following code to the task definition inside the tasks.json file:

"problemMatcher": [
    "$COBOLErrFormat3"
]

The following problem matchers are available for COBOL code:

$COBOLErrFormat2Copybooks - use this followed by the $COBOLErrFormat2 matcher
$COBOLErrFormat2 - matches the build output when the errformat(2) directive is set
$COBOLErrFormat3 - matches the build output when the errformat(3) directive in set
$COBOLMSBuild - use this for COBOL MSBuild projects created with Visual COBOL or Enterprise Developer for Visual Studio
$COBOLAnt- use this for COBOL Eclipse projects created with Visual COBOL or Enterprise Developer for Eclipse
$COBOLAntCopybooks - use this to match errors in copybooks that get emitted by the Ant build of the COBOL Eclipse projects. This matcher can only be used together with the $COBOLAnt problem matcher. $COBOLAntCopybooks should precede $COBOLAnt in the tasks.json file:

"problemMatcher": [
    "$COBOLAntCopybooks",
    "$COBOLAnt"
]

File encodings

Visual Studio Code uses UTF8 by default when opening or creating files. To change the encoding used for COBOL files you can add the required encoding to the settings.json file as follows:

{
    "[cobol]": {
        "files.encoding": "utf8bom"
    }
}

When utf8bom is set, the Compiler will recognise the file encoding as UTF8.

Debugging native COBOL code

Note: A licensed version of Micro Focus Visual COBOL or Micro Focus Enterprise Developer must be installed on the same machine on which you are running Visual Studio Code in order for this feature to work.

Refer to the full documentation of the extension for all of the requirements and for examples of debugging scenarios.

The following outlines the debug process:

Open the folder that contains the file to debug in Visual Studio Code.
Click Run > Add Configuration. This creates a launch.json in a .vscode subfolder in the location of your COBOL file. The file is then opened in the editor.
Specify any debug properties as required - see Specify debug properties.
Open the COBOL program in the editor.
Add any breakpoints as required.
Start debugging - click Run > Start Debugging.

Launch configuration file

Debugging native COBOL code requires a debug launch configuration file that specifies how to debug your COBOL programs. The default launch configurations are COBOL: Launch and COBOL: Attach to process.

You can create additional launch configurations for other debugging scenarios in the launch.json file:

With launch.json opened in Visual Studio Code, click Run > Add Configuration.

You can add one of the following configurations - COBOL: Launch, COBOL: Launch (remote), COBOL: Launch (64-bit), COBOL: Attach to process, COBOL: Enterprise Server, COBOL: Wait for attachment. Optionally, you can add more settings to these as required.

Some of the settings you can specify are:

"args": [ ] - command-line arguments for the program.
"cwd": "${workspaceFolder}" - current working directory. This is set to the workspace folder, by default.
"env": [ {"name": "", "value": "" }] - specify any environment variables as required.

For example, set the following to enable CTF for the program being run. It does not, on its own, result in CTF output in the Debug console. If, however, the CTF configuration file has the 'idedbg' emitter set then CTF output will be displayed in the Debug Console.

    "env": [ {"name": "MFTRACE_CONFIG", "value": "d:\\trace.cfg" }]

"is64bit": true - if you want to debug a 64-bit application. This is set to true by default on Linux.
"program": "${workspaceFolder}/<insert-program-name-here>" - you can specify an executable, or a core dump file.
"remoteDebug" - specify any remote debug settings. You need to have Visual COBOL or Enterprise Developer and cobdebugremote running on the remote machine:

"remoteDebug": {
    "machine": "machine name or IP",
    "port": 0
}

When Remote debugging, file names provided by the debugger will contain paths on the remote file system which may not exist on the local file system. Adding one or more pathMappings maps paths from the remote file system to paths on the local file system allowing the source files to be opened.

"pathMappings": [
    { 
        "remote": "<remote-path>",
        "local": "<local-path>"
    }
]

"symbolSearchPaths": [] - specify the location of the .idy files.
"stopOnEntry": true - the debugger stops on the first line of debuggable code.

Attach to process and debug

You can attach to and debug applications as running processes:

Ensure the application sources are stored on your local machine. Open the folder that contains the source files in Visual Studio Code.
Click Debug > Start Debugging.

This creates a launch.json inside a .vscode subfolder of the folder that contains your sources.

Add the COBOL: Attach to process configuration to the launch.json file:

{
    "type": "cobol",
    "request": "attach",
    "name": "COBOL: Attach to process",
    "processId": "${command:pickProcess}"
}

Select COBOL: Attach to process from the configuration launcher, and click Start Debugging.

This opens the Attach to process widget.
Start typing the name of the executable you want to debug, and then select it.

Wait for a debuggable attachment

Ensure the application sources are stored on your local machine. Open the folder that contains the source files in Visual Studio Code.
Click Debug > Start Debugging.

This creates a launch.json inside a .vscode subfolder of the folder that contains your sources.
Add the COBOL: Wait for attachment configuration to the launch.json file:
```
{
    "type": "cobol",
    "request": "launch",
    "name": "COBOL: Wait for attachment",
    "waitForAttachment": { }
}
```
Where the supported waitForAttachment options are:
- any - Waits for and then attaches to the next COBOL program that calls CBL_DEBUGBREAK, or is launched with the COBSW environment variable set to +A.
- directory - Waits for and then attaches to the next COBOL program that is launched with its working directory set to either the folder specified, or a subfolder of it.
- id - Waits for and then attaches to the next COBOL program which calls CBL_DEBUG_START with the identifier you specify in the ID field as an argument. When using the id option the debugger always returns to the waiting state when the program being debugged exits.
- returnToWait - Only supported with the any and directory options. Optional. Returns the debugger to a waiting state when the program being debugged exits.
Select COBOL: Wait for attachment from the configuration launcher, and click Start Debugging.
Visual Studio Code starts the debugger and displays a message Waiting for debug connection.

Watchpoints

The Run and Debug view includes a WATCHPOINTS window allowing watchpoints to be set.

To add a watchpoint:

Select the Run and Debug view and click WATCHPOINTS.
Click +.
Type the name of a data item in the field and press Enter. The watchpoint is listed in the WATCHPOINTS window, and is enabled by default. You can toggle this watchpoint on and off by right-clicking and selecting Toggle Enable Watchpoint. The icon will be updated accordingly.
To add a condition to the watchpoint (optional):
- Click on the item in the WATCHPOINTS window and expand it.
- Right click on the condition, and then add one or both of the following:
  - An expression: a conditional expression, such as variable EQUALS value. (Bear in mind that 'Breaks when' is prefixed to your expression to form the complete expression. Also, there is no syntax validation of your expression; if it is syntactically incorrect, it just won't work.)
  - A hit count value: this represents the number of times that the area of memory is updated; right-click Edit Hit Count and select from the list of criteria displayed, and then enter the appropriate value. If you define both an expression and a hit count value, both criteria must be satisfied before execution will halt.
- You can toggle the conditions on and off by selecting Toggle Enable Conditions. The icon to the left of the condition indicates whether the condition is enabled.

See the full documentation for further details.

Program breakpoints

The Run and Debug view includes a PROGRAM BREAKPOINTS window allowing program breakpoints to be set.

To add a program breakpoint:

Select the Run and Debug view and click PROGRAM BREAKPOINTS.
Click +.
Type the name of the source file, without the extension, and press Enter. For multi-program source files, to set a break for a sub-program, use its program-id. The program breakpoint is set.

To disable a program breakpoint:

In the PROGRAM BREAKPOINTS window, right-click the required program breakpoint and select Toggle Enable Program Breakpoint to disable it.

To delete a program breakpoint:

In the PROGRAM BREAKPOINTS window, right-click the required program breakpoint and select Delete Program Breakpoint, or to delete all current program breakpoints, click Delete All Program Breakpoints .

See the full documentation for further details.

Viewing memory

In the VARIABLES view, if you select the 'View binary data' icon a memory window is displayed allowing you to view and edit data in the memory associated with the selected item.

Scope of the Support in this Version

This version of the Micro Focus COBOL extension has the following limitations:

Compiling and debugging are supported only if you have a licensed version of a Micro Focus COBOL product on the same machine. See Installing in the full documentation for details.
Compiling of .NET COBOL and JVM COBOL code is supported if the Visual Studio project and/or solution, or the Eclipse project, respectively, are available.
- Debugging of JVM COBOL code is not supported.
Syntax checking is not available and some syntax colorization is not supported at the same level as in Micro Focus Visual COBOL or Enterprise Developer for Visual Studio. For example:
- Uncompiled code and unused variables are not greyed out.
Visual Studio Code provides suggestions as you type in the editor. This functionality is not as advanced as IntelliSense in the Visual Studio editor or as Content Assist in Eclipse.
A problem matcher is not available for the errformat(1) directive.

Micro Focus Visual COBOL or Enterprise Developer provide fully-featured edit, compile and debug support. Click here for further details.