Product Overview

The Rocket® Enterprise Extension for Visual Studio Code provides support for compiling, editing, and debugging COBOL and PL/I source code as well as editing support for Mainframe Assembler, BMS, IMS, and JCL code in Visual Studio Code on Windows and Linux. Support for the COBOL language is supplied by the Rocket® COBOL Extension for Visual Studio Code which is installed when you install the Rocket Enterprise extension.

Main Features

Features include:
  • Editing support for PL/I, COBOL, Mainframe Assembler, BMS, IMS, and JCL. The COBOL and PL/I editors support advanced editing and navigation features provided by the COBOL Language Server or the PL/I Language Server, respectively.
  • Compilation of COBOL, PL/I, BMS, IMS, and Mainframe Assembler code - supports the compiling of source files when either an Eclipse project or a Visual Studio solution file is present, or using custom build scripts.
  • Debugging of native COBOL or PL/I code - offers debug configurations, breakpoints, watchpoints and COBOL program breakpoints, PL/I data breakpoints, conditions and signals, inline values of variables, debugging of applications running on a remote machine or in an Enterprise Server instance, and just-in-time debugging (JIT).
  • Debugging of .NET COBOL programs - offers breakpoints, variables, stepping through code, debug launch configurations, etc.
  • Debugging of JVM COBOL programs - offers breakpoints, stepping through the code, debug launch configurations, etc.
  • Unit testing of COBOL programs through integration with the Micro Focus Unit Testing Framework. You can view, compile, run, and debug tests cases for COBOL applications.
Note:
  • Compiling, debugging, unit testing, and the advanced editor features provided by the COBOL Language Server or the PL/I Language Server require a fully licensed version of a Rocket® Enterprise Developer product installed on the same machine.
  • This documentation includes references to COBOL and PL/I terminology and functionality that are provided with Enterprise Developer. See the documentation of these products for details.
Related tasks
Additional Software Requirements


Getting Started

This sections provides information on how to install this extension and what additional software you need in order to enable its full functionality. Check Configuring for settings you must specify before you start using the extension.

  • Installation
  • Additional Software Requirements
  • Starting Visual Studio Code
  • Configuring
  • Scope of the Support in This Version


Installation

Software Requirements

The Rocket Enterprise extension for Visual Studio Code has the following requirements:

  • Microsoft's Visual Studio Code must be installed. For the Visual Studio Code requirements, see its product documentation.
  • For local application development - a machine that has Windows or Linux installed. macOS is not supported.
  • For remote development - the remote machine onto which you will install the Rocket Enterprise extension must be running Windows or Linux. The local machine on which you run Visual Studio Code itself can be any platform that Visual Studio Code supports.
  • See Additional Software Requirements for software that some of the extension's functionality depends on.

Downloading

You can download the Rocket Enterprise extension from the Visual Studio Marketplace - click here.

Installing

You can install the Rocket Enterprise extension for the first time directly from the Visual Studio Marketplace:

  1. In Visual Studio Code, click View > Extensions.
  2. Enter Rocket Enterprise in the search extensions field.
  3. Click Install in the extension description.

Alternatively, if you have downloaded the .vsix file of the extension:

  1. In Visual Studio Code, click View > Extensions.
  2. Click ... in the Extensions bar, and click Install from VSIX.
  3. Navigate to and select the extension .vsix file on your machine, and click Install.

After Installing

After installing, you might need to configure the extension before you can edit, compile, and debug applications. For example:

  • Specify any configuration details, and any paths to required software in the extension settings - see Configuring.
  • Register COBOL support for the .NET Core debugger or the Java Language Server, if you want to debug .NET COBOL or JVM COBOL programs, respectively. See Debugging .NET COBOL projects or Debugging JVM COBOL Projects.

Updating

  1. In Visual Studio Code, click View > Extensions.
  2. Enter Rocket Enterprise in the search extensions field.
  3. Click [image] (Manage) for the extension, and click Install Another Version.
Note: If you install the Rocket Enterprise extension from the Visual Studio Marketplace, updates will be installed automatically.
Parent topic: Getting Started
Related concepts
Compiling
Scope of the Support in This Version
Related tasks
Additional Software Requirements


Additional Software Requirements

In order to enable the full functionality of this extension, you need the following software installed:

  • A licensed version of one of the products listed below on the same machine. See the table for what features are supported by what products.

    You must specify the install path for the installed product in the Micro Focus COBOL: Install Location setting of the Rocket COBOL extension.

    The earliest supported release is 7.0 unless a newer version is required by a specific feature:

    Rocket Software product (release 7.0 or later) Compiling Debugging

    Native COBOL or PL/I code

            .NET COBOL

    debugging

            JVM COBOL

    debugging

            Micro Focus

    Unit Testing Framework

            Language Server

    functionality

    Rocket® Enterprise Developer for Visual Studio | Check mark | Check mark | Check mark | Check mark 2 | Check mark 1
    Rocket® Enterprise Developer for Eclipse | Check mark | Check mark | Check mark 2 | Check mark 2 | Check mark 1, 3
    Rocket® Enterprise Developer Build Tools (Windows only) | Check mark | Check mark | Check mark | Check mark 2 | Check mark 2 | Check mark 1, 3
    Rocket® Enterprise Server | Check mark
    Rocket® Enterprise Developer Unix Components | Check mark | Check mark | Check mark | Check mark 2 | Check mark 2 | Check mark 1, 3
    • 1The COBOL Language Server requires release 8.0 or later of this product.
    • 2Requires release 9.0 or later of this product.
    • 3The PL/I Language Server requires release 9.0 or later of this product.
  • .NET - the supported version depends on the version of Enterprise Developer that you use. Check the Enterprise Developer product Help for information. .NET is required for:
    • MSBuild and for the COBOL and the PL/I Language Server. MSBuild support is only available on Windows platforms.
    • On Windows for the automatic determination of any Compiler directives specified in the .cblproj or .pliproj project files, created with Enterprise Developer for Visual Studio.
  • Apache Ant - this is required to build Eclipse COBOL or PL/I project (.cobolbuild or .plibuild) files. Ant must be installed and added to the PATH.
  • C# extension - debugging of .NET COBOL projects requires Microsoft's C# extension version 1.23.12 or later for Visual Studio Code.
  • Language Support for Java(TM) by Red Hat extension - debugging of JVM COBOL projects requires the Language Support for Java(TM) by Red Hat extension version 1.16.0 or later for Visual Studio Code.
  • Rocket® JVM COBOL Extension for Visual Studio Code - this is required for JVM COBOL debugging. This will be installed automatically when you register the JVM support inside Visual Studio Code. See Debugging JVM COBOL Projects.
  • Java - debugging JVM COBOL projects requires Java 17. You must specify the path to the bin directory on the Java install location to the PATH environment variable. Your licensed Rocket Software product comes with AdoptOpenJDK.

    Alternatively, you can specify which Java to use from the settings of the Language Support for Java(TM) by Red Hat extension - see the Java > Jdt > LS > Java: Home setting.

  • xterm - debugging on Linux requires xterm, the terminal emulator for the X Window System, which is part of your Linux distribution but is not installed by default. Use your Linux installation media to install it.

The Language Server features, compiling, and debugging require that you specify the location of the prerequisite Rocket Software product in the Rocket COBOL extension settings:

  1. In Visual Studio Code, click View > Extensions.
  2. Click [image] (Manage) for the Rocket COBOL extension, and click Extension Settings.
  3. Specify the full path to the installation directory of the licensed Rocket Software product in the Micro Focus COBOL: Install Location field.
Parent topic: Getting Started
Related concepts
COBOL Language Server
Installation
Product Overview
Compiling Visual Studio Projects
Compiling Eclipse Projects


Starting Visual Studio Code

On Windows:

  • Start Visual Studio Code from the Start menu.

On Linux:

  • Start Visual Studio Code from the command line using the code command.
Parent topic: Getting Started


Configuring

To configure the extension from the Visual Studio Code UI settings:

  1. In Visual Studio Code, click View > Extensions.
  2. Click [image] (Manage) for the extension, and click Extension Settings.

For information on other ways to configure Visual Studio Code, see Microsoft: Visual Studio Code - User and Workspace Settings.

  • Configuring the Editor
  • Settings File (JSON)
  • Configuring Compiling and Debugging
  • Setting Common Compiler Directives with directives.mf
  • Other Settings
Parent topic: Getting Started
Related reference
Microsoft: Visual Studio Code - User and Workspace Settings


Configuring the Editor

You can customize the editor on a global level from the extension settings inside Visual Studio Code.

The editor settings for the Rocket Enterprise extension are as follows:

  • Micro Focus PLI > Editor > Margin: Enable - disabled by default. Check this to enable colorization of the PL/I code.
  • Micro Focus PLI > Editor > Margin: Left - specify the width of the left margin.
  • Micro Focus PLI > Editor > Margin: Right - specify the start of the right margin.
  • Micro Focus PLI: Language Server Autostart - enabled by default. If the PL/I Language Server is available through a licensed Enterprise Developer product, it automatically starts when Visual Studio Code finds PL/I sources in the workspace.
  • Pli Language Server > Trace: Server - specify the level of verbosity between Visual Studio Code and the PL/I Language Server.

In order for most editor features to work, you need to specify the location of the prerequisite Rocket Software product in the Rocket COBOL extension settings - see Micro Focus COBOL: Install Location.

The following lists all editor settings available for the Rocket COBOL extension. Consider changing these if your application uses COBOL programs.

  1. In Visual Studio Code, click File > Preferences > Settings.
  2. Expand Extensions, and click Rocket COBOL or click Micro Focus PL/I.
  3. Use the extension settings:
    • Micro Focus COBOL: Install Location - set this to specify the path to the install location of your licensed Micro Focus Enterprise Developer product. This is required for a number of features, including compiling and debugging, and the language server, to work.
    • Micro Focus COBOL: Language Server Autostart - enabled by default. If COBOL Language Server is available through a licensed Enterprise Developer product, it automatically starts when Visual Studio Code finds COBOL sources in the workspace.
    • COBOL Language Server > Trace: Server - specify the level of verbosity between Visual Studio Code and the COBOL Language Server.
    • You can specify the following editor settings:
      • Micro Focus COBOL > Editor: Custom Tab Stops - Enables you to specify custom tab stops for your programs instead of Visual Studio Code automatically determining the tab stops based on the indent size and the source format. You specify the custom tab stops in the Visual Studio Code settings.json file in the following format:
        {
    "microfocusCOBOL.editor.customTabStops": [
        ArrayNumbers
    ]
}
      • Micro Focus COBOL > Editor: Dialect - the default COBOL dialect for the editor. The default is Micro Focus.
      • Micro Focus COBOL > Editor: Improved Tab Stops - Enabled by default. Depending on the source format of the code, COBOL can have irregular tab stops. This option improves the behavior of the TAB key and the SHIFT+TAB key combination so that it adjusts the indentation of the code based on COBOL tab stops.
      • Micro Focus COBOL > Editor: Source Format - this is used for the COBOL colorization in the editor. The default is fixed.

Add file associations

If your COBOL source files are not colorized, this might be because Visual Studio Code does not have the required file association. To add a file association:

  1. Click File > Preferences > Text Editor > Files.
  2. In the Association section, click Add Item.
  3. Add the file association in the following format:
    .extension
    For example, .ss.
    programming-language
    For example, cobol.

To customize the editor for the current COBOL file:

  • Click the language toolbar status item, {}, in the bottom right corner of the Visual Studio Code main window. Use the Configure buttons for the Source Format and Dialect items in to change the settings only for the currently active file:
    Toolbar buttons
Parent topic: Configuring
Related reference
Microsoft: Visual Studio Code - User and Workspace Settings


Settings File (JSON)

You can specify more editor settings in the global Visual Studio Code settings.json file:

  1. On the Visual Studio Code Settings page, click Open Settings (JSON), ( [image]).

    This opens the global settings.json in the editor. The location of the file is %userprofile%\AppData\Roaming\Code\User (Windows) or ~/.config/Code/User (Linux) for default installations.

  2. Type settings and their values as described in Microsoft: Visual Studio Code - User and Workspace Settings.

    For example, you can configure:

    COBOL rulers
    The Rocket Enterprise extension applies default rulers when you open a COBOL file in the editor. The rules enable you to identify easily the COBOL areas and columns. You can configure these by changing the language defaults in the settings.json. For example, you can change the location of the rulers in the following section:
        "[cobol]": {
        "editor.rulers": [
            6,
            7,
            72
        ]
    }
    Smart Edit and COBOL tab stops
    If you would like to enable editing features that preserve the left hand margin for fixed and variable source format COBOL code, you can enable Smart Edit and improved COBOL tab stops.
    {
    "microFocusCOBOL.editor.improvedTabStops": true,
    "microFocusCOBOL.editor.smartEdit": true
}

    You can customize your tab stops even further by specifying each column that should be a tab stop.

    {
    "microFocusCOBOL.editor.customTabStops": [6, 7, 19]
}
    COBOL Source format and dialect
    Use the following settings:
    {
    "microFocusCOBOL.dialect": "Enterprise COBOL for z/OS",
    "microFocusCOBOL.sourceFormat": "fixed"
}
    Custom colors for the COBOL words
    You can customize the colors of the COBOL words in the editor. This can be useful if your Visual Studio Code theme makes it difficult to see certain colors.

    Use the editor.semanticTokenColorCustomizations property with the rules option, and modify the settings prefixed with cobol. For example:

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


Configuring Compiling and Debugging

You can specify settings for compiling and debugging in the global settings for the Rocket COBOL extension. These apply to Rocket Enterprise as well.

Location of a licensed Rocket Software product

Micro Focus COBOL: Install Location
The root folder of the licensed prerequisite Rocket Software product.

Ant and Java settings

You need to set values for the following settings to be able to compile COBOL projects created in Eclipse:

Ant: Ant_home Path
Specify the path to an Ant installation folder.
Ant: Ant_home Resolve
Specify how Visual Studio Code should determine the location of Ant when compiling Eclipse projects:
  • Use Current Environment - Default. Uses the values set in the current process environment. Ant must be on the PATH and ANT_HOME must be set before you start Visual Studio Code.
  • User Defined - Visual Studio Code uses the value specified in the Ant: Ant_home Path field.
Ant: Java_home Path
Specify the path to the install folder of Java.
Ant: Java_home Resolve
Specify how Visual Studio Code should determine the location of Java when compiling Eclipse projects:
  • Use Current Environment - Default. Uses the values set in the current process environment. Java must be on the PATH and JAVA_HOME must be set before you start Visual Studio Code.
  • User Defined - Visual Studio Code use the value specified in the Ant: Java_home Path setting.

CTF setting

COBOL.CTF: Configuration File
Specify the path to a Consolidated Tracing Facility File (CTF) to be used when launching the debugger or build tasks.

Default Compiler directives to use during compiling

COBOL: Default Directives
Default directives to use to compile a COBOL file when no task with a suffix compileCurrentFile is present. For example, these directives are applied with the commands available through the [image] (Debug/Run) button in the top right corner of the editor task bar, and by the COBOL language server.
PL/I: Default Directives
Default directives to use to compile a PL/I file when no task with a suffix compileCurrentFile is present. For example, these directives are applied with the commands available through the [image] (Debug/Run) button in the top right corner of the editor task bar.

MSBuild settings

The following settings apply when you build COBOL projects created in Visual Studio:

MSBuild: Path
Specify the path to the MSBuild executable on your machine.
MSBuild: Resolve
Specify how Visual Studio Code should determine the location of MSBuild:
  • Autodetect - Default. Visual Studio Code locates and sets the location of MSBuild automatically. It uses the first MSBuild installation it finds.
  • Use Current Environment - Uses the value set in the current process environment. You must add the MSBuild location to the PATH before you start Visual Studio Code
  • User Defined - Visual Studio Code uses the value specified in the MSBuild: Path setting.

Other build settings

Suppress Build Assets Prompt
Disabled by default. When the folder opened in Visual Studio Code contains a Visual Studio COBOL project for creating a .NET COBOL application, Visual Studio Code displays a warning if the launch.json or tasks.json files are not available and prompts to create them. If you do not want to build or debug the application, enable this check box to avoid receiving this message each time you open the folder in Visual Studio Code.
Suppress File Associations Prompt
Disabled by default. Check this if a warning is displayed that file associations have been defined which conflict with this extension.
Terminal: 32bit
Check this to use a 32-bit terminal so that t just sets the environment before starting the terminal so that commands you run in the terminal have the selected bitism.
Parent topic: Configuring


Setting Common Compiler Directives with directives.mf

Use one or more common directive files, directives.mf, to set directives for compiling multiple applications written in one or more programming languages without having to specify all directives individually. Common directives files contain multiple directives that can be applied to multi-language applications at compile time, ensuring that a common set of directives is applied to multiple applications.

The directives.mf file format is supported in the Rocket Enterprise extension, which includes code completion, Outline view, and diagnostic information.

Create a directives.mf file

Create a text file called directives.mf and follow the editorconfig style when writing the file. You can create multiple directives.mf files in different subdirectories. All directives files will be picked up by the Compiler and where an individual directive is defined in multiple locations the most recently compiled file will overwrite previous directives.

For information about how to write a directives.mf file, see Creating a directives.mf file in the Visual COBOL or Enterprise Developer product documentation.

Parent topic: Configuring
Related reference
https://editorconfig.org/
Create a directives.mf file


Other Settings

Enable file nesting in EXPLORER view

You can configure the EXPLORER view to nest related files based on their names from the Visual Studio Code settings.json file. You need to specify the explorer.fileNesting.enabled setting, and provide patterns for the COBOL file extensions being used. For example:

    "explorer.fileNesting.enabled":true,
    "explorer.fileNesting.patterns": {
        "*.cbl": "${capture}.cpy, ${capture}.cpf, ${capture}.cpv, MFU*${capture}.cpy, Test${capture}.cpy",
        "*.CBL": "${capture}.CPY, ${capture}.CPF, ${capture}.CPV, MFU*${capture}.cpy, Test${capture}.cpy"
    }

On case-sensitive file systems, you might need to specify both upper-case and lower-case values, as in the example above, if files using both cases exist.

Custom colorization for COBOL words

Note: Advanced color customization of COBOL words in Visual Studio Code requires a licensed Enterprise Developer product version 10.0 or later.

Use the editor.semanticTokenColorCustomizations option in the settings.json file to customize the colors of COBOL semantic token types. The list of COBOL words has expanded to include select color customization for:

  • cobol-program
  • cobol-function
  • cobol-level78
  • cobol-level88
  • cobol-typedef
  • cobol-file-storage
  • cobol-local-storage
  • cobol-working-storage
  • cobol-thread-local-storage
  • cobol-linkage
  • cobol-section
  • cobol-paragraph.

Set the color of the token in the JSON file by specifying the hex number of the desired color or clicking the color selection square.

Parent topic: Configuring


Scope of the Support in This Version

This version of the Rocket Enterprise extension has some limitations in the areas listed below.

Note: For full edit, compile, and debug capabilities for COBOL and PL/I applications, install one of Rocket Software's products that support a fully-fledged IDE - Enterprise Developer for Eclipse or Visual Studio.

Compiling and debugging

  • Background parse does not support the inclusion of native preprocessors (including COBSQL, HTMLPP, and PREXML).
  • Compiling and debugging are supported only if you have a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation 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 .NET Framework COBOL code is not supported. Debugging of .NET COBOL code is supported.
  • Debugging of JVM COBOL code on a remote machine is not supported.
  • A problem matcher is not available for the errformat(1) directive.
  • Compiling and debugging are not supported if you use Visual Studio Code as a Web extension in a browser.
  • Reading the COBOL Compiler directives set inside Eclipse COBOL project files (.cobolProj) is not supported.

Editor functionality provided by the COBOL Language Server

  • COBOL Language Server is supported only if you have a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
  • In native code, COBOL Language Server only parses COBOL files that have been opened. Any workspace-wide features such as the symbol search only return results for files that have been opened.
  • Background parse does not fully support JVM COBOL.
  • A file in the workspace can only have one project association. If multiple projects reference the same file, it can only be associated with the first project that is scanned.
  • Rename Symbol only works for files that have been opened and parsed.
  • Rename Symbol and Find All References do not support symbols defined in copybooks that are referenced using COPY... REPLACING.
  • .cblproj project files created with Enterprise Developer for Visual Studio:
    • Not supported on Linux
    • SDK-style projects are not supported. The Language Server features are not supported in projects that target .NET Core or .NET versions 5 or newer.
    • The preprocessors settings are not supported.
    • There is no NuGet support. NuGet dependencies are not resolved.

Editor functionality provided by the PL/I Language Server

  • The PL/I Language Server is supported only if you have a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
  • The PL/I Language Server only parses PL/I files that have been opened. Any workspace-wide features such as the symbol search only return results for files that have been opened.
  • A file in the workspace can only have one project association. If multiple projects reference the same file, it can only be associated with the first project that is scanned.
  • Rename Symbol only works for files that have been opened and parsed.
  • .pliproj project files created with Enterprise Developer for Visual Studio are not supported on Linux.
    • The preprocessors settings are not supported.

COBOL notebooks

  • COPY statements do not resolve copybooks in a workspace.
  • The Debug Cell or Step into Cell commands might not work if the cell has not been run first. You can also manually select Notebook: COBOL Notebook Kernel from the Task Picker (Ctrl+Shift+P) to enable debugging.
  • Output is displayed in the debugger output window when debugging rather than in the notebook itself.
Parent topic: Getting Started
Related concepts
COBOL Language Server
Related tasks
Installation


Editing Code

The Rocket Enterprise extension offers editing support for COBOL (including native, native Object-Oriented COBOL, .NET COBOL and JVM COBOL), PL/I, Assembler, BMS, JCL, and IMS code.

You edit source code in Visual Studio Code by opening either individual files or by opening them as part of a folder. Visual Studio Code does not have a project system.

To edit your sources:

  1. Open the folder that contains your sources inside Visual Studio Code.
  2. Open the file you want to edit.

    Visual Studio Code offers colorization of the code in the editor.

  • Writing COBOL and PL/I Code Efficiently
  • COBOL Language Server
  • PL/I Language Server
  • Editing BMS Files in the BMS Painter


Writing COBOL and PL/I Code Efficiently

  • COBOL dialect
  • Code snippets
  • Comments in COBOL code
  • Exploring your COBOL code
  • File encoding
  • Formatting COBOL
  • Navigate to
  • Outline view
  • Rename data items
Note: A number of productivity and navigation features in the COBOL or the PL/I editor depend on the COBOL Language Server or the PL/I Language Server, and require that the respective Server is enabled.

COBOL dialect

When the COBOL Language Server is enabled, it automatically sets the source format and the COBOL dialect for your source code. If it is not possible to automatically determine these, the Language Server sets a default Fixed source format and a Micro Focus dialect.

If the COBOL Language Server is disabled or stopped, the editor applies the default source format and dialect from the extension setting in Visual Studio Code. However, if a specific source format or dialect has been set for the active document, Visual Studio Code applies those instead.

Code snippets

Insert the code constructs for elements of the PL/I or the COBOL language, for example for classes, methods and delegates in .NET COBOL. Snippets are also available for EXEC CICS and EXEC DLI statements.

To insert a code snippet:

  1. Display a drop-down list of suggested code snippets in your code in one of the following ways:
    • Start typing in the Visual Studio Code editor in your COBOL or PL/Ifile.

      To insert EXEC CICS constructs, start typing cics. For EXEC DLI constructs, start typing dli.

    • Alternatively, press CTRL+Space to open the drop-down list with the available code snippets.

    The snippets in the drop-down list are prefixed by a square icon.

  2. Use the arrow buttons to select the snippet you want to use from the list, then press Enter to insert the code.

Commenting out lines of code in COBOL files

  1. Open a COBOL file in the editor and either click on a line you want to comment, or select a few lines to comment out.
  2. Click View > Command Palette, and select Add COBOL line comment or Toggle COBOL line comment.
    • For fixed and variable source format code, this inserts an * in column 7 of the lines you have selected which comments out the code in areas A and AB.
    • For free source format code, this inserts *> at the start of the code on the selected lines.

To remove the line comments, use the Remove COBOL line comment command from the Command Palette.

Exploring your COBOL code

Right-click an item in your COBOL and click:

  • Go to Definition - positions the cursor on the line where the data item is first defined.
  • Go to References - shows a pop-up window with a list of the references. Click on any reference in the list on the right-hand side to navigate to its location in the code.

  • Peek > Peek Call Hierarchy - opens a pop-up window with the list of call hierarchy
  • Peek > Peek Definition - opens a pop-up window with the line of code where the data item is defined.
  • Peek > Peek References - opens a pop-up window with a list of the occurrences of the data item in the code.
  • Find All References - opens the REFERENCES panel and shows a list of the available references. Click on any reference in the list to navigate to its location in the code.
    Note: This command does not work for symbols defined in copybooks that are referenced using COPY... REPLACING.
  • Show Call Hierarchy - show the list of call hierarchy in the REFERENCES panel.

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.

Format COBOL code

To apply COBOL formatting to your program:

  • Right-click in the COBOL editor, and click Format Document.

    This applies consistent formatting and indentation to your sources.

You can use .editorConfig files either in the workspace folder or in a folder higher up to specify any required formatting settings for your sources. See Sharing Code Style Settings with an EditorConfig File in the Visual COBOL or the Enterprise Developer docs.

Navigate to

Press CTRL+P and type one of the following symbols in the widget:

  • @ - lists items in the document outline such as methods, data items, classes only in the current document. Click on an item in the list to navigate to its location in the code.
  • # - lists the symbols in the entire workspace. Divisions and sections are not displayed. Click on an item in the list to navigate to its location in the code.

Outline and breadcrumb navigation

Click on sections, paragraphs or methods in the OUTLINE section to navigate easily the code in larger files:

Clicking an item either in the code or in the OUTLINE section shows that item in the breadcrumb at the top of the editor. You can click on items in the breadcrumb to open the navigation panel as well:

Rename data items

To rename a data item:

  • Right-click an item in your code, and click Rename Symbol

    This renames all occurrences of the symbol across the files in your workspace, including in copybooks.

    Note: Rename only works for files that have been opened and parsed. It does not work for symbols defined in copybooks that are referenced using COPY... REPLACING.
Parent topic: Editing Code
Related concepts
COBOL Language Server


COBOL Language Server

Important: This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.

A number of advanced editing and navigation features of the Rocket Enterprise extension are provided by COBOL Language Server - a feature available when you also have a licensed Enterprise Developer product. The COBOL Language Server features make editing and navigation in your COBOL code more similar to that of Visual Studio or Eclipse.

Features available through the COBOL Language Server

The COBOL Language Server enables the following functionality in your extension and must be running in order for them to work:

  • Context-aware code completion as you type.
  • Hover pop-ups for data items - hovering data items in the source provides a basic description of the data item.
  • Go to/Find/Peek definition and references - provide quick navigation from a data item to its definition or to other locations where the code references it.
  • Go to/Peek definition for copy statements - hover COPY statements to view their full path.
  • Collapsible regions in the editor - you can collapse sections of code in the editor.
  • OUTLINE view - a tree-view outline of a COBOL program that shows the divisions, sections, and data items defined in the program.
  • Error highlighting and reporting - compilation errors are highlighted in the editor and shown in the PROBLEMS section.
  • Rename command available across multiple files.
  • Specify a main file for a copybook.

See Scope of the Support in This Version for details about the limitations of the COBOL Language Server.

Enable the COBOL Language Server

To enable the Language Server, ensure that the Micro Focus COBOL: Install Location is set to the install location of a licensed Enterprise Developer product. Micro Focus COBOL: Language Server must also be enabled. See Additional Software Requirements.

Start or stop the COBOL Language Server

The Micro Focus COBOL Language Server status icon, [image], in the language toolbar status item {} in the bottom right corner of Visual Studio Code shows whether the COBOL Language Server is running:

  1. Click Options on the line for the Micro Focus COBOL Language Server.

    This shows the Task Picker with the available commands:

    • Shutdown - click this if you want to disable the Language Server features temporarily. For example, you might want to switch off the functionality for projects for which the Language Server is not supported.
    • Restart - click this to restart the Language Server.
    • Show output - click this to view any trace messages from the Language Server in the OUTPUT view.
  2. If you switched off the Language Server, click its status icon again to access the Start command.

Determine the Compiler directives

When running, COBOL Language Server determines automatically the Compiler directives for your code. As a result, the Dialect or Source format options in the status bar command are disabled and it is not possible to change them manually.

COBOL Language Server determines directives as follows:

  • It checks the source code for $set statements. This works only for the supported COBOL dialects.
  • It searches for cobol.dir files in the same directory as the source files.
  • It checks if the $COBCPY and $COBDIR environment variables are set before you launch Visual Studio Code. If any of these are set, the Language Server uses them to resolve the location of any copybooks.
  • If a project file is not available, Visual Studio Code takes the directives for background parse from the Default Directives extension setting.

In some circumstances, updating any external files does not automatically trigger a background parse of the files. To manually trigger background parse, right-click in the editor, and click Update syntax reporting.

Automatic directives determination using project files

If the workspace includes any .cblproj files, the COBOL Language Server scans the project files and any COBOL files that are listed in a project get associated with the project.

Note: A file in the workspace can only have one project association. If multiple projects reference the same file, it can only be associated with the first project that is scanned.

When COBOL Language Server is running, the Visual Studio Code status indicates the project the file you edit is associated with in the Project: projname.cblproj field.

This project association means that the background parse uses the Compiler directives and any dependency path information which is available in the project file.

Specify a main file for a copybook

If more than one COBOL programs in the workspace reference the same copybook, you can choose which main COBOL program will provide the context for the copybook. You can do this as follows:

  1. Open the copybook in the editor.
  2. In the language toolbar, click {} in the bottom right corner of Visual Studio Code next to the COBOL language item.
  3. Click Configure on the line for Context file.

    This shows the Task Picker at the top of Visual Studio Code with the list of COBOL programs available to choose as a context.

  4. Select the preferred COBOL program.

    This will be displayed next time you check the context of the copybook with the {} selector.

Parent topic: Editing Code
Related concepts
Writing COBOL and PL/I Code Efficiently
Related tasks
Additional Software Requirements
Scope of the Support in This Version


PL/I Language Server

Important: This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.

A number of advanced editing and navigation features for PL/I sources inside the Rocket Enterprise extension are provided by the PL/I Language Server - a feature available when you also have installed and licensed a supported Enterprise Developer product. The PL/I Language Server features make editing and navigation in your PL/I code more similar to that of Visual Studio or Eclipse.

Features available through the PL/I Language Server

The PL/I Language Server enables the following functionality in your extension and must be running in order for them to work:

  • Hover pop-ups for data items - hovering data items in the source provides a basic description of the data item.
  • Go to/Find/Peek definition and references - provide quick navigation from a data item to its definition or to other locations where the code references it.
  • Go to/Peek definition for include statements - hover include statements to view their full path.
  • Collapsible regions in the editor - you can collapse sections of code in the editor.
  • OUTLINE view - a tree-view outline of a PL/I program that shows the programs, and data items defined in the program.
  • Error highlighting and reporting - compilation errors are highlighted in the editor and shown in the PROBLEMS section.
  • Rename command available across multiple files.
  • Specify a main file for an include file.

See Scope of the Support in This Version for details about the limitations of the PL/I Language Server.

Enable the server

The PL/I Language Server requires that you have a licensed Enterprise Developer product installed on your machine. The Micro Focus COBOL: Install Location setting of the Rocket COBOL extension must set to the install location of Enterprise Developer. See Additional Software Requirements.

Start or stop the server

With a PL/I source opened in the editor, look at the bottom right corner of Visual Studio Code. You can notice that the language toolbar status item, {} PL/I, correctly indicates the language of your source file.

Hover the {} symbol to check the status of the PL/I Language Server. By default it is running:

Click Options on the line for the Micro Focus PL/I Language Server to access the commands for the server available from the Task Picker:

  • Shutdown - click this if you want to disable the Language Server features temporarily. For example, you might want to switch off the functionality for projects for which the Language Server is not supported.
  • Restart - click this to restart the Language Server.
  • Show output - click this to view any trace messages from the Language Server in the OUTPUT view.

If the server is disabled, for example - if the Micro Focus PLI: Language Server Autostart is unchecked, you can start it as follows:

  1. Hover the {} symbol in the language toolbar.
  2. Click Options on the line for the Micro Focus PL/I Language Server.
  3. Click Start available from the Task Picker list.

Determine the Compiler directives

If the workspace includes any .pliproj files, the PL/I Language Server scans the project files and any PL/I source files that are listed in a project get associated with the project to obtain the compiler directives to use.

If a project file is not available, Visual Studio Code takes the directives for background parse from the Micro Focus PLI: Default Directives extension setting.

In some circumstances, updating any external files does not automatically trigger a background parse of the files. To manually trigger background parse, right-click in the editor, and click Update syntax reporting.

Note: A file in the workspace can only have one project association. If multiple projects reference the same file, it can only be associated with the first project that is scanned.

When the PL/I Language Server is running, the Visual Studio Code status indicates the project the file you edit is associated with in the Project: projname.cblproj field.

This project association means that the background parse uses the Compiler directives and any dependency path information which is available in the project file.

Specify a main PL/I file for an include file

If more than one PL/I programs in the workspace reference the same include file, you can choose which main PL/I program will provide the context for the include file. You can do this as follows:

  1. Open the include file in the editor.
  2. In the language toolbar, click {} in the bottom right corner of Visual Studio Code next to the PL/I language item.
  3. Click Configure on the line for Context file.

    This shows the Task Picker at the top of Visual Studio Code with the list of PL/I programs available to choose as a context.

  4. Select the preferred PL/I program.

    This will be displayed next time you check the context of the include file with the {} selector.

Parent topic: Editing Code


Editing BMS Files in the BMS Painter

If you use Visual Studio Code with Enterprise Developer, you can open BMS files in the BMS Painter supplied with Enterprise Developer as follows:

  1. In Visual Studio Code, right-click the .bms file in the folder opened in the EXPLORER pane.
  2. Click Open BMS Painter.

    This starts the BMS Painter utility and opens the file in the painter.

Alternatively:

  1. Open the BMS file in the editor.
  2. Right-click in the editor, and click Open BMS Painter.
Parent topic: Editing Code


Compiling

Important: This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.

Using build tasks to compile your code

Visual Studio Code is a light-weight editor and differs significantly from an IDE (Visual Studio or Eclipse). It supports working with files, folders, and workspaces but does not support projects and does not offer a build system by default. It offers build tasks that are commands and scripts that enable you to use the Enterprise Developer compiler to build your COBOL or PL/I files.

You can access the build tasks from the Terminal menu.

  • Compiling Visual Studio Projects
  • Compiling .NET COBOL Projects
  • Compiling Eclipse Projects
  • Customize Build Tasks
  • Integrate Build Scripts with Tasks
  • Integrate a Problem Matcher
Related tasks
Installation


Compiling Visual Studio Projects

Note:
  • Visual Studio project support is only available on Windows platforms.
  • Compiling Visual Studio projects and solutions requires that you have one of the following Rocket Software products installed:
    • Enterprise Developer for Visual Studio
    • Enterprise Developer Build Tools

The Rocket Enterprise extension provides auto-generated build tasks for any .cblproj, .pliproj or .sln files. The projects can be for native COBOL, PLI/I code, or for .NET COBOL code.

The project and solution must be created with Enterprise Developer for Visual Studio. The .cblproj or the .pliproj file, and the .sln solution file must be stored in the same folder that you open in Visual Studio Code or any subfolder beneath it.

To compile the sources:

  1. Click Terminal > Run Build Task.

    This shows the Task Picker with the supplied build tasks - one for building the project file, and one for building the solution.

    1. Select the file you want to build - for COBOL this is either COBOL: MSBuild (<projname>.cblproj) or COBOL: MSBuild (<slnname>.sln).

      For PL/I code the available tasks are PL/I: MSBuild (<projname>.cblproj) or PL/I: MSBuild (<slnname>.sln)

      You can optionally configure which task should be the default one from this widget.

      The build output is displayed in the Terminal window. Any errors are underlined with red squiggly lines in the editor.

  2. Check the Problems panel for any issues. Double-click any of the rows to navigate to the lines of code in the editor that contain the issue.
Parent topic: Compiling
Related tasks
Additional Software Requirements


Compiling .NET COBOL Projects

Prerequisites

In order for the Rocket Enterprise extension to work with .NET COBOL projects, you need the following software installed:

  • A licensed installation of one of the following Rocket Software products, release 7.0 or later:
    • Enterprise Developer for Visual Studio
    • Enterprise Developer Build Tools
    • Enterprise Developer Unix Components
    Note: Enterprise Developer for Eclipse, and Enterprise Server are not supported.
  • Microsoft's C# extension version 1.23.12 or later for Visual Studio Code.
  • Other software requirements - see the product Help of Enterprise Developer for Visual Studio for any requirements for compiling .NET Core projects.

Build a .NET COBOL Project

Your .cblproj or .sln .NET COBOL projects and solutions must be created with Enterprise Developer for Visual Studio. The .cblproj file must be stored in the same folder as the .sln file, or in a subfolder of it.

  1. Open the folder in Visual Studio Code.

    You can use a command provided by the C# extension to generate the tasks.json and launch.json file for your project.

  2. Invoke the Visual Studio Code Command Palette widget - click Ctrl+Shift+P.
  3. Scroll down, and select Generate assets for .NET COBOL build and debug from the lists of tasks available for the palette.

    This generates a tasks.json and a launch.json file in a .vscode subfolder within the folder that holds your sources. You can use these files to build and to debug your project, respectively.

  4. Click Terminal > Run Build Task to build your project.

Alternatively, if you do not want to create a tasks.json file,Rocket Enterprise provides an auto-generated build task for each .NET COBOL project file in the open folder:

  1. Click Terminal > Run Build Task, and select the auto generated build task, COBOL: dotnet build (projname.cblproj)

Next, see Debug .NET COBOL Projects.

Parent topic: Compiling
Related tasks
Debugging .NET COBOL Projects


Compiling Eclipse Projects

Prerequisites

Compiling Eclipse projects has the following requirements:

  • A licensed version of one of the following Rocket Software products:
    • Enterprise Developer
    • Enterprise Developer Build Tools

    You need to specify the installation location of your licensed product as Micro Focus COBOL: Install Location in the Rocket Enterprise extension settings.

  • Apache Ant must be installed and the path to its bin folder added to the PATH.

You can use the Rocket Enterprise extension to compile COBOL (both native and JVM COBOL) and PL/I source files that include the .cobolBuild or the .pliproj project file created with Enterprise Developer for Eclipse.

If a folder opened in Visual Studio Code contains the .cobolBuild project file, the Rocket Enterprise extension will automatically generate a task for compiling the project via Ant. You can manually configure the build task, if required.

Compiling native COBOLor PL/I code

To compile COBOL sources:

  1. Ensure the folder that contains your sources is opened in Visual Studio Code.
  2. Click Terminal > Run Build Task.

    This shows the Task Picker with the supplied build task:

    Ant build task
  3. Select COBOL: Ant (.cobolBuild) to trigger a build.

    The build output is displayed in the Terminal window. Any errors are underlined with red squiggly lines in the editor.

  4. Check the Problems panel for any issues. Double-click any of the rows to navigate to the lines of code in the editor that contain the issue.

Optionally, you can configure the build task as follows:

  1. Click Terminal > Configure Tasks.
  2. Select COBOL: Ant (.cobolBuild) from the Task Picker.

    This loads the tasks.json file for your sources in the editor.

To compile PL/I sources:

  1. Ensure the folder that contains your sources is opened in Visual Studio Code.
  2. Click Terminal > Run Build Task.

    This shows the Task Picker with the supplied build task:

    Ant build task
  3. Select PL/I: Ant (.pliBuild) to trigger a build.

    The build output is displayed in the Terminal window. Any errors are underlined with red squiggly lines in the editor.

  4. Check the Problems panel for any issues. Double-click any of the rows to navigate to the lines of code in the editor that contain the issue.

Optionally, you can configure the build task as follows:

  1. Click Terminal > Configure Tasks.
  2. Select PL/I: Ant (.pliBuild) from the Task Picker.

    This loads the tasks.json file for your sources in the editor.

Compiling JVM COBOL projects

If your JVM COBOL project contains the .cobolProj project file, the Rocket Enterprise extension will automatically build it after your sources are opened in Visual Studio Code.

Parent topic: Compiling
Related concepts
Debugging JVM COBOL Projects
Related tasks
Additional Software Requirements


Customize Build Tasks

To customize an existing build task:

  1. Click Terminal > Configure Tasks.
  2. Select the task to configure - for example, COBOL: MSBuild (projname.cblproj).

    This creates a tasks.json file in your folder. This file contains the custom build tasks for the current workspace:

    {
    "version": "2.0.0",
    "tasks": [
        {
            "type": "COBOL",
            "msBuildExe": "path to \\MSBuild.exe",
            "buildTarget": "path\\projname.cblproj",
            "group": "build",
            "problemMatcher": [
                 "$COBOLMSBuild"
            ],
            "group": "build",
            "label": "COBOL: MSBuild (projname.cblproj)",
        }
    ]

    If you choose the PL/I build task, PL/I: MSBuild (projname.pliproj), the tasks.json file looks similar to the one for COBOL:

        "version": "2.0.0",
    "tasks": [
        {
            "type": "PLI-MSBuild",
            "command": "path to \\MSBuild.exe",
            "buildTarget": "path\\projname.pliproj",
            "problemMatcher": [
                "$PLIMSBuild"
            ],
            "group": "build",
            "label": "PL/I: MSBuild (projname.pliproj)"
        }
    ]
  3. You can add any settings as required. For example, add the following to the list of argument in your task, if you want this build to compile for release:
                "args": ["/p:configuration=release"]

    The following examples show how you can specify multiple arguments:

    • Specify them separately:
                  "args": ["/p:Configuration=Release", "/p:Platform=x86"]
    • Specify them as a single argument:
                  "args": ["/p:Configuration=Release,Platform=x86" ]
      Or, enclosed in single quotes if separated by a semicolon:
                  "args": ["'/p:Configuration=Release;Platform=x86'" ]
Parent topic: Compiling


Integrate Build Scripts with Tasks

Your source files might not be using an MSBuild or an Eclipse project to build. They might be using a build script instead. In this case, you can create a custom build task that uses the build script.

Rocket Software recommends that you define your own custom shell tasks to invoke the build script. The Rocket Enterprise extension includes a COBOL-shell and a PL/I shell task type that make the required compilation tools such as cobol.exe or mfplx.exe for PL/I code (on Windows) and cob or mpfplx for PL/I code (on Linux)) are available to the build script. This requires the location of the licensed Enterprise Developer product to be set in the Visual Studio Code settings.

The default install location is C:\Program Files (x86)\Micro Focus\Enterprise Developer (for Windows), or /opt/microfocus/EnterpriseDeveloper (for Linux).

To configure a custom build task to use the COBOL-shell task type you add it to the existing tasks.json file in the editor. The following example shows a COBOL build task that invokes a batch file, build.bat. build.bat is then able to use cobol.exe to compile COBOL sources:

        {
           "label": "My custom build",
           "type": "COBOL-shell",
           "command": ".\\build.bat",
           "problemMatcher": "$COBOLErrFormat3",
           "group": "build"
        }

The new custom task, My custom build, will be available when you choose Terminal > Run Build Task.

The following example is of a PL/I build task that invokes a batch file. You can use .mfplx.exe in the batch file to compile the PL/I sources.

        {
            "label": "My PL/I Build",
            "command": ".\\build.bat",
            "type": "PLI-shell",
            "group": {
                "kind": "build",
                "isDefault": true
            }
Parent topic: Compiling


Integrate a Problem Matcher

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 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": [
               "ProblemMatcher"
            ]

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 used
  • $COBOLErrFormat3 - matches the build output when the errformat(3) directive is used
  • $COBOLMSBuild - use this for COBOL MSBuild projects created with Enterprise Developer for Visual Studio
  • $COBOLAnt- use this for COBOL Eclipse projects created with 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"
            ]

The following problem matchers are available for PL/I code:

  • $PLIMSBuild - use this for PL/I MSBuild projects created with Enterprise Developer for Visual Studio
  • $PLIAnt - use this for PL/I Eclipse projects created with Enterprise Developer for Eclipse
Parent topic: Compiling


Debugging

Important:
  • This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
  • Visual Studio Code supports debugging of native COBOL code and for .NET Core COBOL projects created with Visual COBOL or Enterprise Developer for Visual Studio.

Debug features

Visual Studio Code provides the DEBUG CONSOLE as well as a number of panels dedicated to debugging in the Run view - click [image] (Run).

Breakpoints
Add breakpoints by clicking in the editor margin. See the available breakpoints in the Breakpoints panel. You can set conditions such as expressions and hit counts for the breakpoints.
Call stack panel
Shows the stack frames for each thread. Double-click a stack frame to navigate to the source code.
Debug widget
Includes the debug actions.
The Visual Studio Code debug widget
Variables panel
Shows the values of items on the current statement.
Watch view
Enables you to add items to watch as you debug. To view the contents in hexadecimal, type ,h after the name of the item you want to watch.

It is not possible to change the values of items directly in this panel. You can change the values by typing the command in the Debug Console REPL - for example:

Change values at the terminal
  • Overview of Debugging in Visual Studio Code
  • Debug Launch Configurations (Native COBOL)
  • Configure PL/I Debugging
  • Watchpoints
  • Program Breakpoints (Native COBOL)
  • Debugging the Current File
  • PL/I Data Breakpoints
  • PL/I Conditions and Signals
  • Attach to Process
  • Just-In-Time Debugging (Native COBOL)
  • Debug Applications Running in an Enterprise Server (Native COBOL)
  • Debugging .NET COBOL Projects
  • Debugging JVM COBOL Projects
  • Debugging Using the Remote Development Extensions
  • Debugging Using the Integrated Terminal
  • Debugging applications that run on Ubuntu


Overview of Debugging in Visual Studio Code

Debugging in Visual Studio Code requires that you create a launch configuration with the settings which the debugger requires to enable it to debug your COBOL or PL/I code. The following instructions demonstrate how to debug native COBOL or PL/I code with the default launch configuration:

  1. Open the folder that contains your sources in Visual Studio Code.
  2. Ensure that the sources are compiled.
  3. Click (Run > Start Debugging).

    This shows the Task Picker with the available debugging tasks:

  4. Select the task required for your code - either COBOL (native): (native) or PL/I: (native) from the drop-down list. This is the default task provided with the Rocket Enterprise extension for debugging native COBOLor PL/I applications, respectively.

    This creates a launch.json file in a .vscode subfolder in the folder that holds your sources. By default, the launch.json contains two configurations - one for debugging a standalone application, and one for attaching the debugger to a running process. For COBOL these are:

        "configurations": [
        {
            "type": "cobol",
            "request": "launch",
            "name": "COBOL (native): Launch",
            "program": "${workspaceFolder}/<insert-program-name-here>",
            "cwd": "${workspaceFolder}",
            "stopOnEntry": true
        },
        {
            "type": "cobol",
            "request": "attach",
            "name": "COBOL (native): Attach to process",
            "processId": "${command:pickProcess}"
        }
    ]
}

    For PL/I, the configurations are:

        "configurations": [
        {
            "type": "pli",
            "request": "launch",
            "name": "PL/I: Launch",
            "program": "${workspaceFolder}/<insert-program-name-here>",
            "cwd": "${workspaceFolder}",
            "stopOnEntry": true
        },
        {
            "type": "pli",
            "request": "attach",
            "name": "PL/I: Attach to process",
            "processId": "${command:pickProcess}"
        }
    ]

    You can add more configurations to this file as required.

  5. In the Activity bar, click [image] to open the Run panel.

    The two default launch configurations are listed in the Configuration drop-down within the Run panel as follow - for COBOL:

    List of debug configurations

    Or, for PL/I code:

  6. Select the launch configuration, COBOL (native): Launch or PL/I: Launch, and click [image] (Start Debugging).
    Debugging features in Visual Studio Code
  7. Use the commands in the Debug widget to step through the code.
    The Visual Studio Code debug widget
  8. Use the available views to watch how variables change.
  9. As you step through the code, the values of variables on the current line are shown inline in the editor, at the end of the line:
    Inline values of variabes during debugging

    You can control whether to display the inline values with the Microsoft Debug: Inline Values setting of Visual Studio Code.

  10. In the VARIABLES panel, click the View Binary Data icon on a row for a variable.

    This opens a Memory window that enables you to view and edit data in the memory associated with the selected item.

Parent topic: Debugging


Debug Launch Configurations (Native COBOL)

Note:
  • This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
  • The following information applies to native COBOL code.

You can create additional launch configurations for various 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 (native): Launch, COBOL (native): Launch - remote, COBOL (native): Launch - Remote-SSH, COBOL (native): Launch - 64-bit, COBOL (native): Attach to process, COBOL (native): Enterprise Server, COBOL (native): Wait for attachment.

Set or change the following options to control Visual Studio Code's behavior during debugging.

Launch options

program (required)
The full path to the executable the debugger will launch.
or
waitForAttachment (required)
The debugger waits for the program to start in a separate process before attempting to attach to it. The value is an object containing:
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.
returnToWait (optional)
Return the debugger to a waiting state when the program being debugged exits.
or
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.
or
any
Waits for and then attaches to the next COBOL program which calls CBL_DEBUGBREAK, or is launched with the COBSW environment variable set to +A (Windows only).
returnToWait (optional)
Return the debugger to a waiting state when the program being debugged exits.

or

enterpriseServer (required)
The Enterprise Server application debugging options. The value consists of serverName and serverAddress plus optional additional values to control the debugger.
serverName (required)
The name of the server.
serverAddress (required)
The debug listener address for the server to be debugged.
debugType (optional)
The type of application to debug. It must be one of the following:
  • cics (default)
  • ims
  • jcl
  • web
  • any
options (optional)
Any of the following:
  • jcl

    where the JCL options are:

    jobName
    The name of the job.
    jobNumber
    The number of the job in the held queue.
    stepName
    The step that you want to debug.
    topLevelProgram
    The start program to be used when debugging the application.
  • cics

    where the CICS options are:

    user
    The CICS user ID that was used to start the application.
    terminal
    The CICS terminal ID that was used to start the application.
    transaction
    The CICS transaction for the application.
    linkLevelProgram
    The CICS invoked program at which to start to debugging.
  • ims

    where the IMS options are:

    user
    The user ID that was used to when debugging the application.
    terminal
    The logical terminal ID to be used when debugging the application.
    transaction
    The transaction to be used when debugging the application.
    topLevelProgram
    The start program to be used when debugging the application.
  • web

    where the Web Services options are:

    clientIP
    Leave this field empty to enable debugging from any IP address. Specify an IP address to allow debugging only from it.
    serviceName
    Specify the address of the web service to debug. Enter the address and any specific operation that is part of the web service in the format http://namespace/ServiceName#OperationName.
stopOnEntry
Automatically pause the program after launching.
console
Select the launch target for debugging from one of the following values:
  • externalConsole - this is the default value.
  • integratedTerminal
  • externalTerminal
Note: To use this option, you must have a licensed Enterprise Developer product, version 10.0 or later, installed on your machine.
trace
Enable logging of the Debug Adapter Protocol.
cwd
The working directory of the program. Default is the current workspace root.
args
Command line arguments passed to the program. The value can be either a single string or an array of strings.
symbolSearchPaths
Paths to search for program symbol (.idy) files.
env
Environment variables passed to the program. The value can either be an array of name and value objects:
"env": [
{"name": "VAR1", "value": "value1"},
{"name": "VAR2", "value": "value2"},
]
or a list of environment variable names and values
"env": {
"VAR1": "value1",
"VAR2": "value2"
}
envFile
Absolute path to a file containing environment variable definitions. This file has key value pairs separated by an equals sign per line, for example KEY=VALUE.
stopAtStopRun
Suspend debugger at stop run.
stepOverIgnoreInline
Step into inline PERFORM statements when using Step Over.
programBreakpointMainEntryOnly
Program breakpoint on main entry point only.
remoteDebug
When present, this tells the debugger to connect to a remote computer. The value consists of the remote machine name or IP address and the port number that is used by the cobdebugremote or cobdebugremote64 process.
            "remoteDebug": {
                "machine": "machine name or IP",
                "port": nn
            }
is64Bit
Indicates whether the debugger is a 64-bit application. Defaults to false on Windows and true on Linux.
useConsole
Use a console for screen input/output.
Note: This option is deprecated. Use the console option instead.
pathMappings
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 value 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"}
            ],
sourceFileMap
Alternative to the 'pathMappings' entry consisting of a list of path mapping values.
            "sourceFileMap": [
              {
                    "remote-path": "local-path",
            ]
symbolsMustMatchProgram
Require program symbols (.idy) to exactly match the program.

Platform-specific configurations

The above options can be used within predefined platforms.
windows
Include options that are specific to debugging on Windows platforms. For example, to set the program to be run when debugging on Windows:
            "windows": {
                "program": "${workspaceFolder}/Program.exe"
            }
linux
Include options that are specific to debugging on Linux platforms. For example, to set the program to be run when debugging on Linux:
            "linux": {
                "program": "${workspaceFolder}/Program"
            }

Attach options

Set or change the following options to control Visual Studio Code's behavior during debugging:

processId (required)
The process ID to attach to. If processId used, do not use processName.
or
processName (required)
The process name to attach to. If this is used processId should not be used.
Some additional options you can specify are as follows:
  • trace
  • symbolSearchPaths
  • stepOverIgnoreInline
  • programBreakpointMainEntryOnly
  • is64bit
  • cwd
  • pathMappings
  • sourceFileMap
  • symbolsMustMatchProgram

Example - enable CTF tracing

In order to enable CTF tracing for the COBOL program being run, you need to add the following setting:
"env": [ {"name": "MFTRACE_CONFIG", "value": "d:\\trace.cfg" }]

This 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. The idedbg emitter is only available on Windows and therefore the output will only be displayed in the DEBUG CONSOLE on Windows.

As an alternative, on Linux platforms the content of the textfile emitter can be viewed in Visual Studio Code as it is written by opening the Terminal and running the tail command using:

 tail -f <path-to-emitter-file>

For more about CTF Tracing, see the product Help of Enterprise Developer.

Parent topic: Debugging


Configure PL/I Debugging

Note:
  • This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.

A launch.json file is used to configure the PL/I debugger. Visual Studio Code generates a launch.json under the .vscode folder in your workspace. The generated file contains two sections: one that configures debugging for launching scenarios and another that configures debugging for attach to process.

You can create additional launch configurations for various 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 for PL/I: Attach to process, PL/I Enterprise Server, PL/I Launch, PL/I Launch (64-bit), PL/I Launch (remote), PL/I Launch (Remote-SSH), PL/I: Wait for attachment.

Set or change the following options to control Visual Studio Code's behavior during debugging.

Launch options

program (required)
The full path to the executable the debugger will launch.
or
waitForAttachment (required)
The debugger waits for the program to start in a separate process before attempting to attach to it. The value is an object containing:
id
Waits for and then attaches to the next PL/I program which calls PLITEST with the identifier you specify in the ID field as an argument.
enterpriseServer (required)
The Enterprise Server application debugging options. The value consists of servername and serverAddress plus additional values to control the debugger.
serverName (required)
The name of the server.
serverAddress (required)
The debug listener address for the server to be debugged.
debugType (optional)
The type of application to debug. It must be one of the following:
  • cics
  • ims
  • jcl
  • web
  • any
options (optional)
Any of the following:
  • jcl

    where the JCL options are:

    jobName
    The name of the job.
    jobNumber
    The number of the job in the held queue.
    stepName
    The step that you want to debug.
    topLevelProgram
    The start program to be used when debugging the application.
  • cics

    where the CICS options are:

    user
    The CICS user ID that was used to start the application.
    terminal
    The CICS terminal ID that was used to start the application.
    transaction
    The CICS transaction for the application.
    linkLevelProgram
    The CICS invoked program at which to start to debugging.
  • ims

    where the IMS options are:

    user
    The user ID that was used to when debugging the application.
    terminal
    The logical terminal ID to be used when debugging the application.
    transaction
    The transaction to be used when debugging the application.
    topLevelProgram
    The start program to be used when debugging the application.
  • web

    where the Web Services options are:

    clientIP
    Leave this field empty to enable debugging from any IP address. Specify an IP address to allow debugging only from it.
    serviceName
    Specify the address of the web service to debug. Enter the address and any specific operation that is part of the web service in the format http://namespace/ServiceName#OperationName.
stopOnEntry
Automatically pause the program after launching.
trace
Enable logging of the Debug Adapter Protocol.
cwd
The working directory of the program. Default is the current workspace root.
args
Command line arguments passed to the program. The value can be either a single string or an array of strings.
symbolSearchPaths
Paths to search for program symbol (.stb) files.
env
Environment variables passed to the program. The value can either be an array of name and value objects:
"env": [
{"name": "VAR1", "value": "value1"},
{"name": "VAR2", "value": "value2"},
]
or a list of environment variable names and values
"env": {
"VAR1": "value1",
"VAR2": "value2"
}
envFile
Absolute path to a file containing environment variable definitions. This file has key value pairs separated by an equals sign per line, for example KEY=VALUE.
stopAtStopRun
Suspend debugger at stop run.
remoteDebug
When present, this tells the debugger to connect to a remote computer. The value consists of the remote machine name or IP address and the port number that is used by the cobdebugremote or cobdebugremote64 process.
"remoteDebug": {
"machine": "machine name or IP",
"port": 0
}
is64Bit
Indicates whether the debugger is a 64-bit application. Defaults to false on Windows and true on Linux.
useConsole
Use a console for screen input/output.
pathMappings
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 value 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"
}
]
sourceFileMap
Alternative to the 'pathMappings' entry consisting of a list of path mapping values.
"sourceFileMap": {
"remote-path": "local-path"
}

Platform-specific configurations

The above options can be used within predefined platforms.
windows
Include options that are specific to debugging on Windows platforms. For example, to set the program to be run when debugging on Windows:
            "windows": {
                "program": "${workspaceFolder}/Program.exe"
            }
linux
Include options that are specific to debugging on Linux platforms. For example, to set the program to be run when debugging on Linux:
            "linux": {
                "program": "${workspaceFolder}/Program"
            }

Attach options

processId (required)
The process ID to attach to. If processId used, do not use processName.
or
processName (required)
The process name to attach to. If this is used processId should not be used.
Some additional options you can specify are as follows:
  • trace
  • symbolSearchPaths
  • is64Bit
  • cwd
  • pathMappings
  • sourceFileMap
  • useConsole
Parent topic: Debugging


Watchpoints

Restriction:
  • Watchpoints are supported only in native COBOL or in PL/I code.
  • This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.

Watchpoints are a type of breakpoint for that you set on individual data items (not on lines of code). They enable you to watch an area of memory associated with the particular item, and whilst debugging, execution breaks each time the associated memory is updated, or if a condition is attached to the data item, when the condition and/or hit count setting is satisfied. You can set watchpoints either before you start to debug or during your debug session.

Once a watchpoint is set, it is displayed and configured from the WATCHPOINTS panel, where you can:
  • Show a list of the watchpoints that have been set in code.
  • Configure a conditional expression for a watchpoint; the expression can be based on the value of a data item, or based on the number of times that the memory associated with the data item is updated.
  • Add new watchpoints, and disable or delete existing ones.
  • View the current state of each watchpoint during debugging.

To add a watchpoint:

  1. In the Activity bar, click [image] to open the Run and Debug panel, then click the row for WATCHPOINTS.
  2. Click +.
  3. Type the name of the data item in the field, and press Enter.

    The watchpoint is listed in WATCHPOINTS window, and is enabled by default.

  4. You can toggle this watchpoint on and off by clicking [image] Toggle Enable Watchpoint on the line for the watchpoint in the WATCHPOINTS window.

Optionally, to add a condition to the watchpoint:

  1. Click on the item in the WATCHPOINTS panel, and expand it.

    The watchpoint conditions item is displayed.

  2. On the row for the condition, click one of the following buttons:
    • Edit Condition Expression - this starts the command palette for you to type 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 will not work.)
    • Edit hit count - this starts the command palette and opens a drop-down list for you to select a criteria, then enter the appropriate value. This represents the number of times that the area of memory is updated.

    If you define both an expression and a hit count value, both criteria must be satisfied before execution will halt.

  3. You can toggle the conditions on and off by selecting [image] Toggle Enable Conditions. The check mark or X to the left of the condition indicates whether the condition is enabled.

When the watchpoint is enabled, debugging stops on the line that immediately follows the line on which the data has changed.

Parent topic: Debugging


Program Breakpoints (Native COBOL)

Important:
  • This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
  • Program breakpoints are supported only in native COBOL, and are not supported in nested programs.

Program breakpoints are breakpoints that stop execution each time a specified program or entry point within the program is called.

To set a program breakpoint:

  1. In the Activity bar, click [image] to open the RUN AND DEBUG panel, then click the row for PROGRAM BREAKPOINTS.
  2. Click +.
  3. Type the name of the source file, without the extension, and press Enter.

    This sets the program breakpoint.

    For multi-program source files, to set a break for a sub-program, use its program-id.

To disable a program breakpoint:

  • In the PROGRAM BREAKPOINTS window, on the row for the required program breakpoint, click [image] Toggle Enable Program Breakpoint to disable it.

To delete a program breakpoint:

  • In the PROGRAM BREAKPOINTS window, on the row for the required program breakpoint, click X Delete Program Breakpoint, or to delete all current program breakpoints, click [image] Delete All Program Breakpoints on the row for the PROGRAM BREAKPOINTS panel.
Parent topic: Debugging


Debugging the Current File

Important:
  • This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
  • This is not supported in JVM COBOL code. Native COBOL, .NET COBOL, and PL/I code is supported.

Visual Studio Code displays [image] (Debug COBOL Program)for COBOL files or Debug PL/I Program for PL/I files) in the top right corner of the editor task bar. This button enables you to start running or debugging the program which is currently opened in the editor as part of a folder as follows:

  • Click [image] in the top right corner of the editor, and click either Debug PL/I Program or Run PL/I Program.

Before debugging starts, Visual Studio Code compiles the file, either by running the compiler using the default directives specified in the extension settings, or by using a task specified in the tasks.json file.

When no tasks.json file is available

If your workspace does not include a tasks.json file, Visual Studio Code automatically compiles the current file with the directives specified in the Micro Focus COBOL: Default Directives or Micro Focus PL/I: Default Directives setting of the extension depending on the file type, before it starts debugging.

When tasks.json is available

If tasks.json is present, it can include a task with the suffix (compileCurrentFile) to be able to compile the active file. You need to specify any Compiler directives in the args parameter. For example, for COBOL:

        {
            "label": "COBOL: (compileCurrentFile)",
            "type": "COBOL-shell",
            "windows": {
                "command": "cobol.exe",
                "args": [
                    { "value": "${file}", "quoting": "escape"},
                    { "value": "anim", "quoting": "strong"},
                    { "value": "nognt", "quoting": "strong"},
                    { "value": "errformat(3)", "quoting": "strong"},
                    { "value": ";", "quoting": "strong"}
                ]
            },
            "linux": {
                "command": "cob",
                "args": [
                    { "value": "${file}", "quoting": "escape"},
                    { "value": "-C", "quoting": "strong"},
                    { "value": "errformat(3)", "quoting": "strong"},
                ]
            },
            "problemMatcher": "$COBOLErrFormat3",
            "group": "build"
        }

Or, for PL/I:

        {
            "label": "PL/I: (compileCurrentFile)",
            "type": "PLI-shell",
            "windows": {
                "command": "mfplx.exe",
                "args": [
                    { "value": "${file}", "quoting": "escape"},
                    { "value": "-debug", "quoting": "strong"},
                    { "value": "-dc", "quoting": "strong"},
                    { "value": "-stbout", "quoting": "strong"},
                    { "value": "-o", "quoting": "strong"},
                    { "value": "${fileBasenameNoExtension}.exe", "quoting": "escape"}
                ]
            },
            "linux": {
                "command": "mfplx",
                "args": [
                    { "value": "${file}", "quoting": "escape"},
                    { "value": "-debug", "quoting": "strong"},
                    { "value": "-dc", "quoting": "strong"},
                    { "value": "-stbout", "quoting": "strong"},
                    { "value": "-o", "quoting": "strong"},
                    { "value": "${fileBasenameNoExtension}", "quoting": "escape"}
                ]
            },
            "problemMatcher": "$PLIShell",
            "group": "build"
        },

In addition, if you use an MSBuild project file, you can create a build task containing compileCurrentFile that uses the MSBuild project file. This task compiles the active file in the editor. For example:

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "COBOL-MSBuild",
            "command": "C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\Professional\\MSBuild\\Current\\Bin\\MSBuild.exe",
            "buildTarget": "${workspacefolder}/test.cblproj",
            "problemMatcher": [
                "$COBOLMSBuild"
            ],
            "group": "build",
            "label": "COBOL: MSBuild (compileCurrentFile)",
            "args": [
                "/t:CompileSelected",
                "/p:CompileItems=${fileBasename}"
            ]
        }
    ]
}

Or, for PL/I:

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "PLI-MSBuild",
            "command": "C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\Professional\\MSBuild\\Current\\Bin\\MSBuild.exe",
            "buildTarget": "${workspacefolder}/test.pliproj",
            "problemMatcher": [
                "$PLIMSBuild"
            ],
            "group": "build",
            "label": "PL/I: MSBuild (compileCurrentFile)",
            "args": [
                "/t:CompileSelected",
                "/p:CompileItems=${fileBasename}"
            ]
        }
    ]
}
Parent topic: Debugging


PL/I Data Breakpoints

Important:
  • This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
  • This functionality is supported only in PL/I code, and is not available for COBOL.

Data breakpoints are using the address of variables and break the execution of the code when the value of the data changes. To set a data breakpoint:

  1. Start debugging your PL/I application.
  2. In the VARIABLES panel, right-click a variable, and click Break on Value Change.

    This adds a data breakpoint to the BREAKPOINTS panel.

  3. Continue stepping through the code.

    Execution stops when the value of the variable changes.

  4. You can enable or disable the data breakpoint from the BREAKPOINTS panel.
Parent topic: Debugging


PL/I Conditions and Signals

Important:
  • This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
  • This functionality is supported only in PL/I code, and is not available for COBOL.

Conditions

You can instruct the debugger to break and show an error when a PL/I condition has occurred by adding one or more conditions to PL/I Conditions in the BREAKPOINTS view. The supported PL/I conditions are as follows:

  • ANYCONDITION
  • AREA
  • ATTENTION
  • CONDITION
  • CONVERSION
  • ENDFILE
  • ENDPAGE
  • ERROR
  • FINISH
  • FIXEDOVERFLOW
  • KEY
  • OVERFLOW
  • RECORD
  • SIZE
  • SUBSCRIPTRANGE
  • UNDEFINEDFILE
  • UNDERFLOW
  • USERCONDITION
  • USERCONDITION(SS$_UNWIND)
  • VAXCONDITION
  • ZERODIVIDE

Signals

To instruct the debugger to ignore one or more PL/I signals:

  • Add them, using either the signal name or number, to Ignored Signals in the BREAKPOINTS view.

To instruct the debugger to catch one or more PL/I signals:

  • Add them, using either the signal name or number, to Caught Signals in the BREAKPOINTS view.
Note: Avoid adding the same signals in both Ignored Signals and Caught Signals. In such cases, the behavior is undefined as it is dependent upon the order in which the signals are passed to the debugger.
Parent topic: Debugging


Attach to Process

Important:
  • This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
  • The following information applies to native COBOL code and to PL/I code.

You can debug a running application in one of the following ways:

  • Create a launch configuration to attach to the running process
  • Create a launch configuration to launch the debugger and waiting for a debuggable attachment

Attach to a running process

You can attach to and debug applications as running processes:

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

    Select the configuration you want to use, if prompted. This creates a launch.json inside a .vscode subfolder in the folder that contains your sources. The launch.json includes two default configurations - one for launching an application, and the other one for attaching to a process. For example:

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

    For PL/I, this is respectively:

            {
            "type": "pli",
            "request": "attach",
            "name": "PL/I: Attach to process",
            "processId": "${command:pickProcess}"
        }
  3. In the Activity bar, click [image] to open the Run panel.
  4. Select the attach configuration, COBOL (native): Attach to process or PL/I: Attach to process, respectively, from the configuration launcher, and click [image] (Start Debugging).

    This opens the Attach to process widget.

  5. Start typing the name of the executable you want to debug, and then select it.

Wait for a debuggable attachment

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

    This creates a launch.json inside a .vscode subfolder in the folder that contains your sources, and opens the file in the editor.

  3. Click Add Configuration in the bottom right corner.

    This opens a pop-up with the available configurations.

  4. Use the arrow keys to select the COBOL: Wait for attachment or PL/I: Wait for attachment configuration, and add it to the launch.json file.

    For COBOL this is:

            {
            "type": "COBOL",
            "request": "launch",
            "name": "COBOL (native): Wait for attachment",
            "waitForAttachment": {options}

        }

    Where the supported 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.
              {
            "type": "COBOL",
            "request": "launch",
            "name": "COBOL (native): Wait for attachment",
            "waitForAttachment": {
                "any": {}
            }

        }
    • 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.
              {
            "type": "COBOL",
            "request": "launch",
            "name": "COBOL (native): Wait for attachment",
            "waitForAttachment": {
                "directory": "pathtodirectory"
            }

        }
    • 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. For example:
              {
            "type": "COBOL",
            "request": "launch",
            "name": "COBOL (native): Wait for attachment",
            "waitForAttachment": {
                "id": "myid"
            }

        }
    • returnToWait - Only supported with the any and directory options. Optional. Returns the debugger to a waiting state when the program being debugged exits. For example:
              {
            "type": "COBOL",
            "request": "launch",
            "name": "COBOL (native): Wait for attachment",
            "waitForAttachment": {
                "any": {},
                "returnToWait": true
            }

        }

    For PL/I, this adds the following:

    {
    "type": "pli",
    "request": "launch",
    "name": "PL/I: Wait for attachment",
    "waitForAttachment": {
        "id": "<unique-id>"
    }
}

    Where, for PL/I, Visual Studio Code waits for and then attaches itself to the next PL/I program which calls PLITEST with the identifier you specify in the unique-id field as an argument.

  5. Select COBOL (native): Wait for attachment or PL/I: Wait for attachment from the configuration launcher, and click [image] (Start Debugging).
  6. Visual Studio Code starts the debugger and displays a message Waiting for debug connection.
Parent topic: Debugging


Just-In-Time Debugging (Native COBOL)

Note:
  • This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
  • The following information applies to native COBOL code only.

You can use Visual Studio Code as the just-in-time (JIT) debugger in the following scenarios:

  • Your COBOL application calls the CBL_DEBUGBREAK library routine
  • Your COBOL application is launched with the COBSW environment variable set to +A
  • Your COBOL application encounters an error

JIT debugging support has the following requirements:

  • The directory in which the application's executable is running must contain the COBOL source code.
  • There should be no instances of Visual Studio Code already running on your machine.
  • Ensure that Visual Studio Code is the JIT debugger for your machine.

You can register Visual Studio Code as the JIT debugger in one of the following ways:

Use a command from the Command Palette on Windows

By default on Windows, the Visual COBOL or Enterprise Developer product installed on your machine is the default JIT debugger for COBOL applications. You can register Visual Studio Code as the JIT debugger on your machine as shown below if you want to use it for JIT debugging without using the COBCONFIG environment variable:

  • Run the command COBOL: Register VS Code as the JIT debugger from the command palette.

    This replaces the value specified by the main COBOL product installation to use either Eclipse or Visual Studio as debugger.

To restore the original value of the JIT debugger for COBOL:

  • Run the command COBOL: Unregister VS Code as the JIT debugger from the command palette.

    This unregisters the Visual Studio Code JIT debugger.

In addition, if you have either Visual COBOL for Eclipse or Enterprise Developer for Eclipse installed, you must disable the Enable JIT debugging setting from Preferences > Micro Focus > COBOL > Debug.

Use a COBOL Run-Time System configuration file

You can use Visual Studio Code as the JIT debugger if you create a COBOL run-time configuration file with the location of the JIT debugger, and then set the COBCONFIG environment variable to that file. This ensures that Visual Studio Code will be launched for just-in-time debugging.

  1. Create a run-time configuration file that contains the following line:
    Windows:
    set debugger_command="extension-folder\\bin\\debugadapter\\win-x86\\MicroFocus.VsCodeDebugProtocol64.exe %%P%X"

    Linux:

    set debugger_command="<extension-folder>/bin/debugadapter/linux-x64/MicroFocus.VsCodeDebugProtocol"

    You must specify extension-folder as a full path. The name of the extension in the Visual Studio Code extensions folder is rocketsoftware.rocket-cobol-<version>.

    Tip: You can use the command COBOL: Configure COBCONFIG for JIT debugging from the Command Palette to add the information to an existing .cfg file, or to update the value if it is already present in the .cfg file, rather than setting it manually.
  2. Set the COBCONFIG environment variable to the configuration file - follow the links below for instructions.
Important: Previous versions of this Visual Studio Code extension used the MicroFocus.VSCodeJIT.exe (Windows) and the MicroFocus.VSCodeJIT executable (UNIX). For any .cfg file in which the debugger_command value is set to these executables, run the COBOL: Configure COBCONFIG for JIT debugging from the Command Palette in order to change the value to the new executables.
Parent topic: Debugging
Related reference
COBCONFIG


Debug Applications Running in an Enterprise Server (Native COBOL)

  • This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
  • The following information applies to native COBOL code only.

You can debug a native COBOL application which runs under Rocket Enterprise Server. The application's executable runs in the enterprise server instance either on the same, or on a remote machine. In order to debug the application:

  1. Ensure that the enterprise server instance is running. You can do this in the Enterprise Server Common Web Administration (ESCWA).

    You can access ESCWA on the machine that has Enterprise Server installed at the following address: http://localhost:10086 (or https://localhost:10086, if Enterprise Server has certain security features enabled).

    1. Click the NATIVE tab in the UI.
    2. From the pane on the left, expand Directory Servers.
    3. Click the server you want to start, and click the Start button next to its name.

    For more information about ESCWA, see the Enterprise Server product Help.

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

    This creates a launch configuration file, launch.json.

  4. Add the COBOL (native): Enterprise Server configuration to the launch.json file:
            {
            "type": "cobol",
            "request": "launch",
            "name": "COBOL (native): Enterprise Server",
            "enterpriseServer": {
                "serverName": "Please enter the name of the server to debug.",
                "serverAddress": "Please enter the address of the 'mfcs-mp' or 'soap' listener for the server. eg tcp:127.0.0.1:<nnn>."
            }
        },

    Edit the values for serverName and serverAddress as follows:

    • serverName - the name of the enterprise server instance as it appears in the list of Directory Servers inside the Enterprise Server Common Web Administration (ESCWA).
    • serverAddress - the address of the mfcs-mp listener property of the enterprise server instance. To get its address:
      1. In ESCWA, click the NATIVE tab in the UI.
      2. From the pane on the left, expand Directory Servers and select your Enterprise Server instance.
      3. From the General drop-down list, select Listeners.
      4. Under Communication Processes, click Web Services and J2EE.
      5. In the Listener Properties pane, note and copy the entire string in the Address field - e.g. tcp:198.0.0.1:9003.
  5. Select COBOL (Enterprise Server) from the configuration launcher, and click [image] (Start Debugging).
Parent topic: Debugging


Debugging .NET COBOL Projects

Prerequisites

In order for the Rocket Enterprise extension to work with .NET COBOL projects, you need the following software installed:

  • A licensed installation of one of the following Rocket Software products, release 7.0 or later:
    • Enterprise Developer for Visual Studio
    • Enterprise Developer Build Tools
    • Enterprise Developer Unix Components
    Note: Enterprise Developer for Eclipse, and Enterprise Server are not supported.
  • Microsoft's C# extension version 1.23.12 or later for Visual Studio Code.
  • Other software requirements - see the product Help of Enterprise Developer for Visual Studio for any requirements for compiling .NET Core projects.

Register COBOL debugging support

Before you can debug .NET COBOL projects, you need to register the COBOL debugging support. You only need to do this once:

  1. Invoke the Visual Studio Code Command Palette widget - click Ctrl+Shift+P.
  2. Scroll down and select the COBOL: Register COBOL support with .NET Core debugger (vsdbg) command.

    This adds the COBOL support to the .NET debugger. If Microsoft's C# extension is not installed, this action will install it as well.

Debug a .NET COBOL project

To launch debugging, you must define a launch configuration in the launch.json file.

  1. See Compile .NET COBOL Projects for information about how to create a launch.json file for your project.
  2. Note that the launch.json file includes launch configuration of type coreclr which is provided by the C# extension. The following is an example of a launch configuration:
            {
            "name": ".NET Core Launch (console)",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "COBOL: dotnet build",
            // Specify the executable that should be debugged below
            "program": "${workspaceFolder}/bin/Debug/net6.0/demo.exe",
            "args": [],
            "cwd": "${workspaceFolder}",
            // For more information about the 'console' field, see https://aka.ms/VSCode-CS-LaunchJson-Console
            "console": "internalConsole",
            "stopAtEntry": false
        },
  3. Click Run > Start Debugging and debug your project in the usual way.
Parent topic: Debugging
Related tasks
Compiling .NET COBOL Projects


Debugging JVM COBOL Projects

Prerequisites

To debug JVM COBOL projects in Visual Studio Code, you need to install the following software:

  • The Rocket JVM COBOL extension for Visual Studio Code. Visual Studio Code installs this automatically when you register JVM COBOL support for debugging. Alternatively, you can install this extension from the View > Extensions pane.
  • A licensed installation of one of the following Rocket Software products, release 9.0 or later:
    • Enterprise Developer for Eclipse
    • Enterprise Developer Build Tools
    • Enterprise Developer Unix Components
    Note: Enterprise Developer for Visual Studio, and Enterprise Server are not supported.
  • A minimum of Java 17 installation - You must specify the path to the bin directory of the Java install location within the PATH environment variable. Your licensed Rocket Software product comes with AdoptOpenJDK.

    Alternatively, you can specify which Java to use from the settings of the Language Support for Java(TM) by Red Hat extension - see the Java > Jdt > LS > Java: Home setting.

  • Set the system environment variable JAVA_HOME to the install location of your Java.
  • Add the path to the bin subfolder within the system PATH environment variable.
  • Other software requirements - see the product Help of Enterprise Developer for Eclipse for any requirements for compiling JVM COBOL projects.

Register the JVM support

After installing the Rocket JVM COBOL extension, you need to register JVM support inside Visual Studio Code to be able to debug JVM COBOL projects. You only need to do this once:

  1. Invoke the Visual Studio Code Command Palette widget - click Ctrl+Shift+P.
  2. Scroll down or start typing Register JVM COBOL, then click Register JVM COBOL support with Java Language Server (JDT LS).

    This adds the COBOL support to the JVM debugger. If not installed, this will also download and install the Rocket JVM COBOL extension for Visual Studio Code.

Alternatively:

  1. The first time you open some JVM COBOL sources in the EXPLORER pane, you receive a message in the bottom right corner of Visual Studio Code:
    Additional setup is required to build and debug COBOL JVM code.
  2. Click Setup in the dialog box to register the JVM support.

    Registering JVM support automatically installs the Language Support for Java(TM) extension by Red Hat.

Create a debug launch configuration

Before you can start debugging, you need to create a launch.json file for your sources.

  1. Click Run and Debug [image] in the Activity bar to open the RUN panel.
  2. Click create a launch.json file.

    This starts the command palette list showing the available options.

  3. Click COBOL: (JVM).

    This creates a launch.json file in your working folder, and opens it in the editor. The file includes one default JVM COBOL debug configuration for launching the current COBOL file.

  4. If necessary, add a configuration suitable for your sources - click Add Configuration in the bottom right corner of the editor.

The following launch configurations are available for debugging JVM COBOL code:

  • COBOL (JVM): Launch Program - this configuration requires you to specify the main class.
            {
            "type": "coboljvm",
            "name": "Launch COBOL JVM Program",
            "request": "launch",
            "mainClass": ""
        }
  • COBOL (JVM): Launch Program in Current File - you need to open a program in the editor. The debugger automatically locates the main class in the currently open file.

    If there is more than one main method, Visual Studio Code displays a drop-down list, and enables you to select the class to debug.

            {
            "type": "coboljvm",
            "name": "Launch Current File",
            "request": "launch",
            "mainClass": "${file}"
        }
  • COBOL (JVM): Launch Program with Arguments Prompt - when you start debugging, Visual Studio Code prompts you to specify any additional arguments to pass to the debugger.
            {
            "type": "coboljvm",
            "name": "Launch with Arguments Prompt",
            "request": "launch",
            "mainClass": "",
            "args": "${command:SpecifyProgramArgs}"
        }

Configurations can have the following parameters:

  • projectName – the preferred project in which the debugger searches for classes. This is helpful when different projects define classes with identical names. This setting also works when the debugger looks for the specified main class when launching a program. It is required for expressions evaluation.
  • mainClass – the fully qualified class name (such as com.xyz.MainApp) or the file path to the JVM COBOL program.
  • args – any command-line arguments to pass to the program.
  • vmArgs - any additional options and system properties for the JVM (such as -Xms<sizes> -Xmxs<sizes> -Ds<names>=s<values>).
  • classPaths - the classpaths for launching the JVM. If not specified, the debugger will automatically resolve this using the current project.
  • cwd - the working directory of the program. Defaults to the current workspace.
  • env – any additional environment variables for the program.
  • stopOnEntry - automatically pause the program after launching.

The following configuration is available for attaching and debugging running processes:

  • COBOL (JVM): Attach to process - in the launch.json file you can specify a configuration to attach to a running process.
        {
            "type": "coboljvm",
            "name": "COBOL (JVM): Attach to process",
            "request": "attach",
            "hostname": "localhost",
            "port": "8001"
        }

The following configuration property is optional for COBOL (JVM): Attach to process:

  • timeout - the amount of time in milliseconds that Visual Studio Code waits until it attaches to the running process. The default value is 20000 ms (20 seconds).
Note: If the value of timeout is set to zero the timeout will wait forever to attach.

Debugging JVM COBOL projects

To launch debugging:

  1. Set any breakpoints in your programs as required.
  2. In the EXPLORER pane, click Run > Start Debugging.
  3. Debug your project in the usual way.
  4. Check the TERMINAL and PROBLEMS pane for any messages. There is a different debug terminal for each program you debug.
Parent topic: Debugging
Related concepts
Compiling Eclipse Projects


Debugging Using the Remote Development Extensions

Important: This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.

The following information applies when you use Visual Studio Code to debug applications that use character screens for input/output on a remote Linux machine and you use the Remote-SSH extension to connect to the machine.

If the application being debugged contains any screen I/O, you need to interact with the application in a window on the desktop. The debugger must be set up to allow the information to appear in an X terminal. These are the steps to enable this support:

  1. On the remote Linux machine - ensure that X11 Forwarding is enabled in the SSH configuration for the remote machine. The following options must be set:
    • Set ForwardX11 to yes
    • Set ForwardX11Trusted to yes
  2. On your local machine that has Visual Studio Code - ensure that an X-Server is running.
  3. From your local machine, connect an X terminal to the remote machine. This enables the X11 forwarding.
  4. Get the value of DISPLAY - for example, execute the following command at the terminal:
    echo $DISPLAY

    This typically is a value such as localhost:10.0.

  5. Do not close this X terminal otherwise the X11 forwarding required by the debugger does not remain active.
  6. Add the following environment variables to the debug configuration launch.json file for the application to be debugged in Visual Studio Code:
                "env": [
                { "name": "DISPLAY", "value": "<The value obtained from the X terminal>"},
                { "name": "TERM", "value": "xterm"}
            ]

    When you start debugging the application, an X terminal is displayed containing the screen I/O for the application.

See the Remote COBOL Development topic for more details about how to set up a remote SSH connection for remote development.

Parent topic: Debugging
Related concepts
Remote Development


Debugging Using the Integrated Terminal

Important: This functionality requires a licensed version of a Enterprise Developer product, version 10.0 or later, on the same machine. See Installation for details.

The following information applies when you use Visual Studio Code to debug applications that use character screens for input/output.

If the application being debugged contains any screen I/O, you need to interact with the application. You can use the integrated terminal to debug applications in the following scenarios:

  • Running locally without using a separate console window or application output window.
  • Running on a remote Linux system without having to install an X-Server on your local system.
  • Running in a devcontainer without requiring the xterm support to be installed in the devcontainer.
  • When Visual Studio Code is running in a web browser and using a remote tunnel to connect to a remote system.

To use the integrated terminal, add the following to the debug configuration file, launch.json, for the application to be debugged in Visual Studio Code:

"console": "integratedTerminal"

where the other options for the console are externalTerminal and externalConsole (Windows only).

Parent topic: Debugging


Debugging applications that run on Ubuntu

Important: This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
Note: The following topic applies to applications running on Linux, and when using Docker.

On Linux-based platforms, by default, a process can only attach to another process if it has a predefined relationship with it. An example would be a parent process that has started a child process. This is a restriction to ptrace and is valid for non-root users only. It is designed to ensure higher security to malware attacks. The root user can still attach to any process.

This affects unsolicited Dynamic Attachment debugging.

This behavior is defined by the sysctl value in /proc/sys/kernel/yama/ptrace_scope, which is set to 1, by default.

To relax the restriction and allow processes to attach to other processes, this value must be set to 0. This allows processes that have the same user id to attach to each other. Execute the following to remove the restriction:

sudo sh << END
echo 0 > /proc/sys/kernel/yama/ptrace_scope
END

If the launch.json file contains a COBOL: Attach to process configuration or if you use Visual Studio Code for dynamic attachment, then you might need to set ptrace_scope to zero in order to enable the debugger to run.

Parent topic: Debugging


Micro Focus Unit Testing Framework Support

The Rocket Enterprise extension supports TEST EXPLORER integration for the unit testing framework, MFUnit, provided by the Enterprise Developer products.

Prerequisites

  • A licensed installation of a Rocket Enterprise Developer product, release 9.0 or later.
  • Specify the location of the licensed product in the extension setting Micro Focus COBOL: Install Location.

The TEST EXPLORER shows unit tests within your workspace, and enables you to run and debug them in Visual Studio Code.

Alternatively, you can compile your Visual Studio or Eclipse COBOL test projects from the command line. See The Micro Focus Unit Testing Framework in your Enterprise Developer product documentation for details.

Configure test discoverers

A discoverer defines where unit tests are located within a workspace and which runner and COBOL environment should be used to load them. In the settings.json file, use the setting microFocusCOBOL.mfunit.discoverers to configure your test discoverers. To set one or more discoverers:

  1. In Visual Studio Code, click File > Preferences > Settings.
  2. Expand Extensions, and click Rocket COBOL.
  3. Go to the setting Micro Focus COBOL > Mfunit: Discoverers, and click Edit in settings.json.

    This opens the settings.json file with the discoverers option ready for input.

As an example, two discoverer configurations can look like:

{
    "microFocusCOBOL.mfunit.discoverers":	[
        {
            "globPattern": "bin/*.{dll, so}",
            "is64Bit": false,
            "runner": "mfurun",
        },
        {
            "globPattern": "bin.net/*.dll",
            "is64Bit": false,
            "runner": "mfurunil",
        }
    ]
}

Where the following runner options are available in Windows:

Option | Executable | Notes
mfurun | mfurun.exe | Use with native COBOL.
mfurunil | mfurunil.exe | Use with .NET COBOL.
mfurunil6 | mfurunil6.exe | 64-bit only if using a Rocket Software product 9.0 release or later. Use with .NET COBOL.
mfurunj | mfurunj.bat | Use with JVM COBOL.

The following runners are used for UNIX platforms.

Option | Notes
cobmfurun_t | Use with threaded RTS.
cobmfurun | Use with non-threaded RTS.
cobmfurunil6 | 64-bit only if using a Rocket Software product 9.0 release or later. Use with .NET COBOL.
cobmfurunj | Use with JVM COBOL.

Once a discoverer has been set, you can build the COBOL sources and any tests found in the globPattern will be populated in the TEST EXPLORER. If the unit tests do not populate the TEST EXPLORER:

  1. Go to the Output pane, click the output channel drop-down list and select Micro Focus Unit Test Discovery.
  2. View the information concerning unit tests to diagnose the problem.

View and run tests

  1. Compile your source files as instructed in the Compiling section of the documentation.
  2. After compiling, click Testing [image] to open the TEST EXPLORER. This displays all unit tests in your workspace.
  3. You can run all unit tests in your workspace by clicking Run Tests in the toolbar of the TEST EXPLORER. You can also run individual tests by clicking Run Test next to a test file.

    A test can pass, fail, or encounter an error. The result is indicated by the symbol next to the test file.

  4. Click [image] (Show Output) in the toolbar to view the Test Output tab in the Terminal.

  5. Click the Test Results panel to view the output of any tests.

Debug tests

  1. Set one or more breakpoint(s) in the unit test you want to debug.
  2. Click Debug Tests in the toolbar of TEST EXPLORER to debug all unit tests.
  3. Click Debug Test to debug an individual test file.
  4. Step through the code as normal using the Debug Console.


Scenarios

The following scenarios show how you can use Visual Studio Code with the Rocket Enterprise extension.

  • Remote Development
  • Accessing a Rocket Software Product Running in a Container


Remote Development

Important: This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.

A common scenario for when you can use Visual Studio Code with the Rocket Enterprise extension is if you want to make quick edits to your COBOL or PL/I applications running on a remote machine.

The following demonstration shows how you can use Visual Studio Code with the Rocket Enterprise extension from a local machine to edit, compile, and debug a COBOL application that runs on a remote Linux machine. On your local machine you do not need to have any Rocket Software products installed nor to have the COBOL sources.

An existing Microsoft technology enables you to connect your local Visual Studio Code to remote machine using SSH. It initializes a Visual Studio Code server on the remote machine that has direct access the COBOL sources stored on the remote machine while managing them from the local Visual Studio Code interface.

Local machine setup

First, you need to prepare your local machine. You need to install Visual Studio Code and set it up to connect to the remote Linux machine.

  1. From your Visual Studio Code, install the Remote Development extension pack from Microsoft. This installs three extensions - for remote connections using SSH, Containers, and WSL, the Windows Subsystem for Linux. For this demonstration you are going to use an SSH connection.
  2. Follow the instructions in the Visual Studio Code documentation to connect to your remote machine via SSH: click here for details. This includes instructions about setting up the OpenSSH client on your local machine.

Note that you do not need any Rocket Software products on your local machine nor your COBOL sources.

Remote machine

On your remote Linux machine, you need the following:

  • SSH must be enabled for this machine.
  • Visual COBOL Development Hub or Enterprise Developer UNIX Components installed and licensed.

Sample program

For this demonstration, we are going to use the tictac sample available with the installed Rocket Software products. In real life scenarios, the executable files will be stored on the remote machine so you do not need to compile your code. In this demonstration, you are going to see how you can compile as well.

Copy the tictac.cbl file from its original install location to a working directory on the remote machine. You are going to need a script file that includes the command to compile the source code:

  1. Create a shell script, build.sh, in the directory that contains the tictac.cbl file.
  2. Add the following code to it:
    cob -xg -C errformat=3 tictac.cbl
    Where errformat=3 sets the ERRFORMAT Compiler directive for when you are building the source code. You need to compile with this directive in order to get the error information to include in Visual Studio Code with a Problem Matcher.
  3. Run the following command to give the script executable permissions:
    chmod +x ./build.sh

Because the tictac application uses character screens for Input and Output, you also need to ensure that the information can appear in an X terminal. Follow the instructions in the Debugging Using the Remote Development Extensions topic.

Create an SSH connection in Visual Studio Code to the remote machine

  1. Start Visual Studio Code and note the [image] (Open Remote Window) in the bottom left corner of the UI.

    This button is provided by the Remote extension pack. You can check the status that it displays to know whether the particular Visual Studio Code instance you are looking at is running on the local or the remote machine.

  2. Click [image] (Open Remote Window). This opens the list of the Remote extension commands:

  3. Click Remote-SSH: Connect to Host in order to establish an SSH connection to the remote machine.
  4. Click Add New SSH Host.
  5. In the connection command widget, specify your connection details for the Linux machine: UserName@machineNameorIPaddress, then press Enter.

    This starts a new instance of Visual Studio Code.

  6. Check the status bar next to [image] in the new instance which shows that Visual Studio Code is trying to connect to the remote machine. You can see a notification in the bottom right corner that SSH is being installed on the remote machine and that Visual Studio Code server is initialized on it as well.
  7. Click Linux in the widget asking you to specify the platform the remote machine is running.
  8. Enter your password for the account for the remote machine when prompted.

    Visual Studio Code installs Visual Studio Code server on the remote machine. Note that the status next to the [image] button shows the IP address of the remote machine.

You are now running a local instance of Visual Studio Code that is connected to the remote machine and can access its file system and the Rocket Software COBOL environment on it. There are no Rocket Software products installed locally.

Open the directory on the remote machine that contains your sources

  1. In the new instance of Visual Studio Code, click File > Open Folder.

    This opens the Open Folder widget. This is showing a UNIX-style path which confirms you are connected to the remote machine.

  2. Navigate to the working directory on the remote machine that has your tictac program, and click OK.

    This now shows the files in the folder that contains the tictac example.

  3. Open the tictac.cbl file:

    Note that the editor does not show any colorization yet. This is because you do not have the Rocket COBOL extension installed yet.

Install the Rocket Enterprise extension

You are now going to install Rocket Enterprise in the Visual Studio Code server instance running on the remote machine:

  1. In the new instance of Visual Studio Code, open the Extensions panel.
  2. Search for the Rocket Enterprise extension in the online Visual Studio Marketplace, and install it.

    Alternatively, you can install it from a .vsix file saved to your local machine.

    Visual Studio Code shows a notification once the installation has completed. It also shows a notification that you need to install Visual COBOL or Enterprise Developer in order to enable compiling and debugging. In the next section, you are going to configure the extension to use the Rocket Software COBOL product which is already installed on the remote machine.

    The COBOL source opened in the editor from the remote machine is now colorized which means the editing support provided by Rocket COBOL is now available.

  3. Check the Extensions panel and note that the extension is not displayed in the list of locally installed extensions. Instead, it is shown as installed via SSH in Visual Studio Code server on the remote machine:

Enable compiling and debugging support

In order to be able to compile and debug your COBOL sources, you need to specify the location of a licensed Rocket Software product in the extension. As the extension is installed on the remote machine thanks to Visual Studio Code server and the Remote-SSH extension, you can specify the location to the Rocket Software product already available on the remote machine:

  1. Open the extension settings - click [image] (Manage) for the extension, and click Extension Settings.
    1. Enter the location of your Rocket Software COBOL product in UNIX format in the Micro Focus COBOL: Install Location field.

      The default install locations are /opt/microfocus/EnterpriseDeveloper and /opt/microfocus/VisualCOBOL, respectively, but your product might be installed in a different location.

Compile your source code

Visual Studio Code uses build tasks to compile source code. You created the build.sh script that includes the necessary compile instructions so you need to integrate this file into a build task:

  1. Click Terminal > Run Build Task.

    As there are no predefined tasks, the selection widget provides an option for configuring one.

  2. Click Configure Build Task, then Create tasks.json file from template, and then Others.

    This creates a default tasks.json file in a .vscode subdirectory in the working directory on the remote machine where your tictac program is stored.

  3. Edit the task as follows to add your build script as the command to execute, and also to integrate a Problem Matcher that matches any errors in the COBOL source:
            {
            "label": "cobol",
            "type": "COBOL-shell",
            "command": "./build.sh",
            "problemMatcher": ["$COBOLErrFormat3"],
            "group": "build"
        }
  4. Click Terminal > Run Build Task again, and select the cobol task from the widget.

    This triggers a build. Check the Terminal panel to see if it has completed and if there were any issues with it.

    The executable and debuggable files have been created as well and are visible in the working directory - tictac, tictac.idy, tictac.int, and tictac.o.

Debug your source code

You are now ready to debug your application:

  1. Click Run > Start Debugging.
  2. Click COBOL: (native).

    This creates a template launch.json file with two default debug configurations in the .vscode subdirectory. You are going to use the one that launches the application - the one that has "name": "COBOL (native): Launch". You need to change this configuration to launch the tictac executable.

  3. In the file, replace:
    "program": "${workspaceFolder}/<insert-program-name-here>",

    With:

    "program": "${workspaceFolder}/tictac",
  4. Click Run > Start Debugging again.

    Visual Studio Code enters debug mode and the cursor is positioned on the first executable statement in your COBOL program.

  5. Check the Debug Console and the panels available in the Debug view to see that you're debugging the code on the Linux file system.
Parent topic: Scenarios
Related tasks
Debugging Using the Remote Development Extensions


Accessing a Rocket Software Product Running in a Container

Important: This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
Update: On Ubuntu platforms, a more advanced example of running a development container is available as a demonstration. It uses script files to install the necessary base image and prepare sample projects that can be opened within a development container in Visual Studio Code. See The Development Containers Demonstration for the Enterprise Developer Base Image in your full development product documentation for more information.

The following demonstration shows how you can use Visual Studio Code with the Rocket Enterprise extension to edit, compile and debug a COBOL applications in a Docker container that has either Visual COBOL or Enterprise Developer installed in it.

On the local machine, you only have Visual Studio Code and the sources of your COBOL application. You do not need a Visual COBOL or Enterprise Developer product installed locally.

An existing Microsoft technology enables you to connect your local Visual Studio Code to a container, a Linux container in this demonstration. This enables you to mount your COBOL sources from the local machine into the container, and use Visual COBOL or Enterprise Developer installed in it.

Prerequisites

This demonstration requires the following:

  • A Windows machine with Visual Studio Code
  • Docker Desktop
  • Docker Support for Visual COBOL or Enterprise Developer - this is available from the OpenText Software Licenses and Downloads site, if you have a license for Visual COBOL or Enterprise Developer.

Local machine

First, you need to prepare your local machine, install Visual Studio Code and ensure it can connect to a Docker container. The local machine does not need a Visual COBOL or Enterprise Developer product installed on it.

  • Install Visual Studio Code.
  • In Visual Studio Code, install Microsoft's Remote - Containers extension. This is also included in the Remote Development extension pack from Microsoft so you can install either extensions.

    The extension enables you to mount the sample files into the container from the local file system and use Visual COBOL or Enterprise Developer installed in the container. You then work with Visual Studio Code as if you were developing locally on your machine though the source files are now isolated inside the container.

Sample program

This demonstration uses the HelloWorld demonstration supplied with the COBOL Docker images for Enterprise Developer and Visual COBOL 7.0.

For example, you can find the Program1.cbl file in the Visual COBOL Build Tools Docker image, and in the Examples\Build_HelloWorld\src subfolder supplied with the image archive.

  1. Save Program1.cbl into a folder on your machine, such as c:\DockerSample, which we will refer to as the workspace folder.
  2. Create a text file in the same folder, and rename the file to bld_src.sh. This script will contain the compile instructions for your source file in the Linux environment.
  3. Edit the file in a text editor, and add the following code to it:
    ls -ld . *

cob -vx -C anim Program1.cbl -o HelloWorld
if [ "$?" -gt 0 ]; then exit $?;  fi

Docker container

  1. Install Docker Desktop on your local machine.
  2. Download the Dockerfiles and build a Docker Image containing the Visual COBOL Development Hub product.
  3. Start the image inside Docker Desktop.

Open the sample program in Visual Studio Code

  1. Open the folder that contains the sample program in Visual Studio Code.
  2. Open Program1.cbl in the editor - there is no colorization in the editor because there is no extension in Visual Studio Code to provide support for the COBOL language.

Next, you need to add a file to your workspace that prepares it to work with a container.

  1. Click [image] (Open Remote Window). This opens the list of the Remote extension commands:

  2. Click Remote - Containers: Add Development Container Configuration files, and then click Show All Definitions.
  3. Select a definition such as Bash.

    This adds a devcontainer.json file inside a .devcontainer subfolder of the sample's folder.

  4. Open the file in Visual Studio Code and change its contents to the following:
    {
    "name": "COBOL DevHub",
    "image": "image-name",

    // Set *default* container specific settings.json values on container create.
    "settings": {
        "terminal.integrated.shell.linux": "/bin/bash",
        // Point to the install location of your Micro Focus product which is installed in the container
        "microFocusCOBOL.installLocation": "/opt/microfocus/VisualCOBOL"
    },

    "extensions": [
        "RocketSoftware.rocket-cobol"
    ]

}

    Where image-name must be the name of your image exactly as shown in Docker Desktop.

    This code specifies which Docker image Visual Studio Code should use, and what settings to apply when you start it. It also installs the Rocket Enterprise extension for you when the container starts the first time.

    In this case, it sets the settings on the remote end automatically.

    The microFocusCOBOL.installLocation setting indicates where the Visual COBOL or Enterprise Developer product is installed in the container.

    The last part that has RocketSoftware.rocket-cobol in the extensions property will enable Visual Studio Code to install the extension from the Visual Studio marketplace when the container is created.

Reopen Visual Studio Code in the Container

Now that the devcontainer.json file includes the link to the container your folder will be mounted in, you can connect your Visual Studio Code with the container.

  1. Click [image] (Open Remote Window). This opens the list of the Remote extension commands:
  2. Click Remote-Containers: Reopen in Container.

    This starts the process of reloading Visual Studio Code in container mode, starts the container with the settings you have specified, and volume mounts your local files in the container.

    Click Starting in Dev container (show log) in the right bottom corner of Visual Studio Code.

    If you see a Desktop - Filesharing dialog appear in the Windows task bar - click Share It.

  3. See the messages in the TERMINAL pane showing Visual Studio Code connecting to the container. Once this is complete, check the Remote connection button - it now shows that Visual Studio Code is connected to your container.

Installing the Rocket Enterprise extension

The .devcontainer file includes the instructions to download and install the Rocket Enterprise extension in Visual Studio Code inside the container. To check that the extension has been installed:

  1. In Visual Studio Code, open the Extensions panel.
  2. Check the Extensions panel and note that the extension is not displayed in the list of locally installed extensions. Instead, Visual Studio Code shows that it is installed in the container:

Build your application

In order to build your application, you need to add a tasks.json file to your folder:

  1. In Visual Studio Code, click Terminal > Configure Tasks.
  2. Click Create tasks.json file from template and click Others.

    This creates a tasks.json inside a .vscode subfolder in your samples folder, and opens the file in the editor.

  3. Edit the file to modify the name of the task, add a command to execute the build script in a Linux environment, and add the task to the build group of tasks:
    {
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "MyCOBOLBuild",
            "type": "COBOL-shell",
            "command": "./bld_src.sh",
            "group": "build",
            "problemMatcher": []
        }
    ]
}
  4. Click Terminal > Run Build Task, and select MyCOBOLBuild.

    This performs a build of your program inside the container.

  5. Check the TERMINAL pane to see the output messages. Note that there is a Linux-style path from setting the environment which confirms you are running the build in the container.
  6. Check the folder in Visual Studio Code - you can see the .idy, .int and .o files produced by the build.
  7. Type ls in the TERMINAL pane. This starts a new bash view and lists the contents of the folder as mounted in the container:
    COBDIR set to /opt/microfocus/VisualCOBOL
user@adbf71521d5b:/workspaces/DockerSample> ls
bld_src.sh  HelloWorld  Program1.cbl  Program1.idy  Program1.int  Program1.o
user@adbf71521d5b:/workspaces/DockerSample>

Debug your application

Debugging with Visual Studio Code in the container is the same as debugging on the local machine. You need to add a launch.json file to your workspace:

  1. In Visual Studio Code, click Run > Add Configuration, and click COBOL: (native).

    This creates a launch.json file in the .vscode folder.

  2. Delete the second attach configuration and replace <insert-program-name-here> with the name of the executable for your program:
    {
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "cobol",
            "request": "launch",
            "name": "COBOL: Launch",
            "program": "${workspaceFolder}/Program1.int",
            "cwd": "${workspaceFolder}",
            "stopOnEntry": true
        },
    ]
}
  3. Open Program1.cbl and add a breakpoint somewhere in the code.
  4. Click Run > Start Debugging.

    This starts the debugger inside the container.

  5. Step through the program. Check the values of items added to the WATCH WINDOW, and note the Linux-format paths in the CALL STACK.
Note: The debugger for Linux is a self-contained .NET Core application. Therefore, the image used needs the relevant packages that are required by .NET Core to be installed. See Microsoft: Install .NET on Linux for more information.
Parent topic: Scenarios
Related reference
Microsoft: Install .NET on Linux


COBOL Notebooks

The Rocket Enterprise extension supports COBOL notebooks, which have the file extension .cblnb. COBOL notebooks enable you to write executable COBOL code cells and Markdown cells in one document. Notebooks can compile either as native COBOL or as .NET COBOL code. You can configure certain settings to apply to individual cells or to the notebook as a whole.

  • Create a COBOL notebook
  • Add code and Markdown cells
  • Add and remove Compiler directives
  • Editing cells
  • Run code cells
  • Debug code cells
  • Other options
  • Restrictions
Note: The COBOL Language Server features are available to use within COBOL notebooks if you have a licensed Enterprise Developer product release 9.0 or later installed on your machine

Create a COBOL notebook

In Visual Studio Code:

  1. Click File > New File.
  2. Select New COBOL Notebook from the drop-down list of file types. If it is not listed, type COBOL Notebook. Alternatively, in the EXPLORER view, click New File [image] to create a new file. When naming the file, add the .cblnb extension and the editor will change accordingly to show the layout for a blank COBOL notebook.

Add code and Markdown cells

To add a cell to a COBOL notebook:

  1. Click Add Code Cell [image] at the top-left of the notebook or in the center of the editor to add a COBOL code cell.
  2. Click Add Markdown Cell [image] at the top-left of the notebook or in the center of the editor to add a Markdown cell.

The cell type is labelled in the bottom right corner of each cell. Markdown cells are blank, whereas code cells contain the four division lines characteristic of COBOL programs.

Add and remove Compiler directives

To add a compiler directive on a notebook level:

  1. In the toolbar of the notebook, click Add directive [image].
  2. Type your directive in the Add directive box at the top of the editor.
  3. After you have added a new directive, the option to remove that directive becomes visible. Click Select directive(s) to delete [image] in the notebook toolbar to remove a directive from the drop-down list.
To add a compiler directive for a specific code cell inside a notebook:
  1. At the bottom of the code cell, click Add directive [image].
  2. Type your directive in the Add directive box at the top of the editor.
  3. After you have added a new directive, the option to remove that directive becomes visible. Click Select directive(s) to delete [image] in the cell to remove a directive from the Select directive(s) to delete drop-down list.

Editing cells

  1. To edit a code cell, click anywhere in the cell, and begin typing.
  2. To edit a Markdown cell, double-click the cell or press enter.

If you have a licensed Enterprise Developer product release 9.0 or later, you will have access to the following COBOL Language Server functionality within notebooks:

  • Context-aware code completion
  • Hover pop-ups for data items
  • Collapsible regions in code cells
  • Error highlighting and reporting
  • Rename Symbol
  • Go to/Find/Peek definition and references

Run code cells

There are multiple ways to execute a cell. You have the option of running all cells within a notebook or running individual cells.

  1. Click Run [image] to run to the left of a code cell to run it.
  2. Click Run All [image] in the notebook toolbar to run all cells in a notebook.

The output of a code cell is shown directly below the cell.

COBOL notebooks can compile native and .NET COBOL. By default, the code type is set to native. To change to .NET COBOL:

  1. Click Cell type for run/debug [image] at the bottom of an individual code cell, or click Cell type for run/debug [image] in the notebook toolbar to set all code cells.

    This opens the drop-down list at the top of the editor.

  2. Select .NET code from the drop-down list.
  3. Run the cell(s).

Debug code cells

Note: You need to run a cell before you can debug it.

Debugging a COBOL notebook follows the same procedures as debugging a COBOL program in Visual Studio Code. For more information on debugging, see the Debugging section.

  1. Set any breakpoint(s) in a code cell by clicking to the left of the line number.
  2. Click Run > Debug Cell to the left of the cell to start debugging.

    This opens the Debug widget, which enables you to step into and through your code.

  3. In the Activity bar, click Run and Debug [image] to open the Run and Debug view. The breakpoint information is visible in the Breakpoints panel.
  4. Step through the code using the Debug widget.

Other options

You can manipulate cells by clicking More Actions [image] in the top right corner of a cell. Additional commands available for COBOL notebooks include:

  • More Actions > Edit Cell Command Line Arguments - add command line arguments in the Add Command Line Argument box. If you select the Edit Cell Command Line Arguments option again you can delete the previously specified argument(s).
  • More Actions > Edit Cell ACCEPT Values - provide a value for ACCEPT statements in the Add ACCEPT Value box. If you select the Edit Cell ACCEPT Values option again you can delete the previously specified value.
  • Provide Input to Cell - click Provide Input to Cell [image] if you are required to enter a value when running a code cell, and type the value in the Provide Input box. Use this as an alternative to the Add ACCEPT Value option.

Restrictions

  • COPY statements do not resolve copybooks in a workspace.
  • The Debug Cell or Step into Cell commands might not work if the cell has not been run first. You can also manually select Notebook: COBOL Notebook Kernel from the Task Picker (Ctrl+Shift+P) to enable debugging.
  • Output is displayed in the debugger output window when debugging rather than in the notebook itself.
Related concepts
Debugging
Writing COBOL and PL/I Code Efficiently
COBOL Language Server


Help With the Extension

Visit the Rocket Software Community Forum for help with the extension and to discuss this product with other users and Rocket Software specialists.

For help with functionality in the extension that relies on your licensed Rocket Software Enterprise Developer product, you can also contact OpenText Support for Micro Focus Products at https://www.microfocus.com/en-us/support.


Copyright and Disclaimer

© 2024 Rocket Software, Inc. or its affiliates. All Rights Reserved.

2024-09-13


.NET

Microsoft's .NET is a free, open-source framework that provides .NET support on multiple platforms.

.NET started as the .NET Core implementation, a rewrite of the .NET Framework. .NET Core (version 1 to 3.n) and the .NET Framework (up to versions 4.n) were different offerings. .NET Core was renamed to .NET in its version 5 and .NET versions 5 and later are the successor of the .NET Framework.