Product Overview

The Micro Focus Enterprise extension 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 Micro Focus COBOL extension which is installed when you install the Micro Focus Enterprise extension.

Main Features

Features include:
  • Editing support for PL/I, Mainframe Assembler, BMS, IMS, and JCL. The COBOL editor support includes basic syntax colorization, source format, dialect recognition, comments, and COBOL tabs.
  • 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 Core COBOL programs - offers breakpoints, variables, stepping through code.
Note:
  • Compiling, debugging, and the advanced editor features provided by the COBOL Language Server require a fully licensed version of a Micro Focus Enterprise Developer product installed on the same machine. See Additional Software Requirements for details.
  • This documentation includes references to COBOL and PL/I terminology and functionality that are provided with Micro Focus 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
  • Micro Focus End User License Agreement
  • Additional License Authorizations for Micro Focus Enterprise Extension for Visual Studio Code


Installation

Software Requirements

The Micro Focus 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 Micro Focus 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 Micro Focus Enterprise extension from the Visual Studio Marketplace - click here.

Installing

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

  1. In Visual Studio Code, click View > Extensions.
  2. Enter Micro Focus 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.

Updating

  1. In Visual Studio Code, click View > Extensions.
  2. Enter Micro Focus Enterprise in the search extensions field.
  3. Click [image] (Manage) for the extension, and click Install Another Version.
Note: If you install the Micro Focus 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 a Micro Focus Enterprise Developer product on the same machine. You must specify the install path for this product in the Micro Focus COBOL: Install Location setting of this extension.

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

    Micro Focus product (release 5.0 or later) Compiling Debugging

    Native COBOL or PL/I code

            .NET Core COBOL

    debugging

            Language Server

    functionality

    Enterprise Developer for Visual Studio Check mark

    Debugging PL/I code requires release 7.0 or later of this product.

    Requires release 7.0 or later of this product.

    Requires release 8.0 or later of this product.

    Enterprise Developer for Eclipse Check mark

    Debugging PL/I code requires release 7.0 or later of this product.

    Requires release 8.0 or later of this product.

    Enterprise Developer Build Tools (Windows only) Check mark

    Debugging PL/I code requires release 7.0 or later of this product.

    Requires release 7.0 or later of this product.

    Requires release 8.0 or later of this product.

    Enterprise Server

    Debugging PL/I code requires release 7.0 or later of this product.

    Enterprise Developer Unix Components Check mark

    Debugging PL/I code requires release 7.0 or later of this product.

    Requires release 7.0 or later of this product.

    Requires release 8.0 or later of this product.

  • MSBuild support is only available on Windows platforms.
  • 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 .NET Core COBOL projects requires Microsoft's C# extension version 1.23.12 or later for Visual Studio Code.
  • 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.
  • .NET Core 3.1, .NET 5 or 5 - required on Windows for the automatic determination of any Compiler directives specified in the .cblproj project files, created with Enterprise Developer for Visual Studio.

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

  1. In Visual Studio Code, click View > Extensions.
  2. Click [image] (Manage) for the extension, and click Extension Settings.
  3. Specify the full path to the installation directory of the licensed Micro Focus product in the Micro Focus COBOL: Install Location field.
  4. The Language Server also requires that Micro Focus COBOL: Language Server setting is enabled.
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
  • Configuring Compiling and Debugging
  • Other Settings
Parent topic: Getting Started
Related reference
Microsoft: Visual Studio Code - User and Workspace Settings


Configuring the Editor

To customize the editor on a global level from the extension settings inside Visual Studio Code:

  1. In Visual Studio Code, click File > Preferences > Settings.
  2. Expand Extensions, and click Micro Focus 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 - Enabled by default. Control wether to use the COBOL Language Server, if available through a licensed Enterprise Developer product.
    • 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.
      • 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.
      • Micro Focus PL/I > Editor > Margin: Enable - disabled by default. Check this to enable colorization of the PL/I code.
      • Micro Focus PL/I > Editor > Margin: Left - specify the width of the left margin.
      • Micro Focus PL/I > Editor > Margin: Right - specify the start of the right margin.

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 Micro Focus 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
        ]
    }
    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",
}

To customize the editor for the COBOL file open in it:

  • Use the Dialect and Source Format buttons in the toolbar in the bottom right corner of the Visual Studio Code main window 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


Configuring Compiling and Debugging

You can specify the following settings for compiling and debugging in the global settings for the Micro Focus COBOL in Visual Studio Code as follows:

Location of a licensed Micro Focus COBOL product

Micro Focus COBOL: Install Location
The root folder of the licensed Micro Focus COBOL 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 Core 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 A warning is displayed if 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


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.

Parent topic: Configuring


Scope of the Support in This Version

This version of the Micro Focus 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 Micro Focus's COBOL products that support a fully-fledged IDE - Enterprise Developer for Eclipse or Visual Studio.

Compiling and debugging

  • Compiling and debugging are supported only if you have a licensed version of a Micro Focus 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 and of JVM COBOL code is not supported. Debugging of .NET Core COBOL code is 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 Micro Focus 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.
  • 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.
Parent topic: Getting Started
Related concepts
COBOL Language Server
Related tasks
Installation


Micro Focus End User License Agreement

IMPORTANT: LICENSOR PROVIDES LICENSED SOFTWARE TO LICENSEE UNDER THIS END USER LICENSE AGREEMENT (THE "AGREEMENT"). THIS AGREEMENT GOVERNS LICENSEE’S INSTALLATION AND USE OF THE VERSION OF THE LICENSED SOFTWARE IDENTIFIED IN THE APPLICABLE PRODUCT ORDER, OR IF NOT ACQUIRED VIA A PRODUCT ORDER, LICENSEE’S INSTALLATION OR USE OF THE LICENSED SOFTWARE CONSTITUTES ACCEPTANCE OF THIS AGREEMENT. THE TERMS AND CONDITIONS OF THIS AGREEMENT MAY BE DIFFERENT FROM THE AGREEMENT(S) THAT ACCOMPANIED EARLIER RELEASES OF THE LICENSED SOFTWARE. PLEASE READ THIS AGREEMENT CAREFULLY BEFORE PROCEEDING, AS IT MAY CONTAIN ADDITIONAL RESTRICTIONS ON YOUR USE OF THE SOFTWARE. THIS AGREEMENT SUPERSEDES AND CONTROLS OVER ANY OTHER TERMS PROVIDED TO LICENSEE REGARDING LICENSEE’S USE OF THE LICENSED SOFTWARE, WHETHER WRITTEN OR ORAL, AS PART OF A SIGNED AGREEMENT (INCLUDING, BUT NOT LIMITED TO, MASTER AGREEMENTS AND PORTFOLIO TERMS, UNLESS A DIFFERENT AGREEMENT IS EXPRESSLY REFERENCED IN A PRODUCT ORDER OR EXECUTED BY LICENSOR AND LICENSEE SPECIFYING THAT IT APPLIES TO THE VERSION OF THE LICENSED SOFTWARE TO WHICH THIS AGREEMENT RELATES), A CLICK-WRAP AGREEMENT PROVIDED WITH THE LICENSED SOFTWARE OR OTHERWISE (SUCH TERMS REFERRED TO AS THE "OTHER AGREEMENT"), EVEN IF SUCH OTHER AGREEMENT WAS EMBEDDED WITHIN PREVIOUSLY LICENSED SOFTWARE. LICENSOR RESERVES THE RIGHT TO UPDATE, AMEND, AND/OR MODIFY THIS AGREEMENT FROM TIME TO TIME, AND MAY INCLUDE SUCH UPDATED AGREEMENT WITH OR EMBEDDED IN FUTURE VERSIONS OF THE LICENSED SOFTWARE. PLEASE DIRECT ANY QUESTIONS TO THE MICRO FOCUS LEGAL DEPARTMENT AT LEGALDEPT@MICROFOCUS.COM.

ENTERING INTO THIS AGREEMENT DOES NOT CONSTITUTE A SALES TRANSACTION. THE SALE OF A LICENSE TO SOFTWARE PRODUCTS TAKES PLACE UNDER PRODUCT ORDERS WHICH (UNLESS OTHERWISE STATED IN THE PRODUCT ORDER) INCORPORATE THE TERMS OF THIS AGREEMENT.

Capitalized terms in this Agreement are defined as follows:

"Additional License Authorization" or "ALA" means the additional specific software license terms that govern the authorized use of a given software product of Licensor, including requirements for any non-production use rights described in the Non-Production Licensing Guide, and License Options available for that software product, along with additional terms or conditions applicable to a given License Option, all of which are made a part of this Agreement. The applicable Additional License Authorization for the Licensed Software is either attached hereto or can be found here: https://software.microfocus.com/en-us/about/software-licensing by product name and version; all references in this Agreement to "Additional License Authorization" or "ALA" shall refer to the ALA that corresponds to the version of the Licensed Software.

"Documentation" means the user documentation that Licensor makes available for the Licensed Software in electronic form or paper form.

"Licensee" means the legal entity or individual that is identified in the applicable Product Order or who has rightfully received a license to the Licensed Product.

"License Option" means the type of license available for a given software product (such as a named user license, concurrent user license or server license). In addition to the ALA, a License Option may be set forth in a Product Order or an agreement executed in writing by Licensee and Licensor.

"Licensor" means the applicable Micro Focus entity and its affiliates who own the intellectual property rights in Licensed Product.

"Licensed Product" means the Licensed Software and Documentation.

"Licensed Software" means the executable version of Licensor’s software listed in the Product Order or otherwise provided to or rightfully acquired by Licensee. This Agreement shall govern the use of any update to the Licensed Software that Licensee receives pursuant to a separate support and maintenance agreement as described in Section 4 below, unless such update contains, comes with, or is otherwise specifically governed by a different end user license agreement.

"Product Order" means an agreement between Licensor and Licensee that consists of a document that has been (i) submitted by Licensee describing the License Option(s) to be purchased for the Licensed Software, and (ii) accepted by Licensor (a) in writing or (b) by delivering the Licensed Software to Licensee, whichever occurs first. A Product Order may also consist of a written quote, or other written document issued by Licensor (the "Quote"), (i) describing the License Options for the Licensed Software to be purchased, and (ii) that is accepted by Licensee before the Quote expires either by (a) returning the Quote signed by an authorized representative of Licensee, (b) issuing a purchase order that references the Quote (if the Quote expressly allows acceptance in this manner), or (c) paying Licensor the fees listed in the Quote. Unless otherwise expressly set forth in the relevant Product Order, each Product Order incorporates the terms and conditions of this Agreement, and in no event will any different or additional terms of a purchase order or similar document issued by Licensee in connection with this Agreement or a Product Order apply, and any such additional or different terms are hereby rejected by the Licensor. For purposes of this paragraph, "Licensor" shall also include the relevant Micro Focus entity as defined above and its authorized distributors and resellers. Any conflicting or additional terms in a Product Order accepted by an authorized distributor or reseller of Licensor shall have no effect unless such terms have been agreed to by the applicable Micro Focus entity in writing.

"Third Party Component" means any run time or other elements owned or licensed to Licensor by a third party (other than open source code or elements) which may be embedded in the Licensed Software.

"Third Party Software" means additional or accompanying software owned or licensed by a third party (such as Adobe Acrobat or Microsoft Internet Explorer, but not any open source code or elements) that may be specified in the Documentation or in a file accompanying such Licensed Software.

"Warranty Period" means the ninety (90) day time frame beginning on date of delivery of the Licensed Software to Licensee (Licensed Software delivery is deemed to occur when the Licensed Software is physically delivered to Licensee EXWORKS or made available for download to Licensee).

  1. GRANT OF LICENSE; LICENSE CONDITIONS.
    1. License Grant. Subject to Licensee’s compliance with the terms and conditions of this Agreement (including but not limited to payment of applicable fees), Licensor grants to Licensee a personal, non-transferable, non-sublicensable and non-exclusive license to use the Licensed Software as authorized by the License Option(s) specified in the ALA solely for Licensee’s internal business operations, functions and benefit, and not for commercialization of the Licensed Software or to provide services or benefit to any affiliates or subsidiaries of Licensee or any other third party. Throughout the license term, Licensee agrees to: (i) implement internal safeguards to prevent any unauthorized copying, distribution, installation, use of, or access to, the Licensed Products and associated support and maintenance, or any other breach of this Agreement; and (ii) take all necessary steps to destroy or erase all Licensed Software codes, programs, Documentation, and other proprietary information of Licensor before disposing of any media or hardware. Licensor will provide any license key necessary for activation and use of the Licensed Software. Licensor is not liable or responsible for lost or broken license keys and is not obligated to replace license keys or issue new license keys unless (1) Licensee has purchased a support and maintenance plan for the applicable Licensed Software that specifically covers the issuance of new or replacement keys and (2) the applicable version of the Licensed Software is then generally available for distribution by Licensor. If Licensee has not paid for such a support and maintenance plan, replacement or new license keys may be available for purchase at Licensor’s then-current list price for applicable new licenses.
    2. Evaluation Licenses. With respect to any Licensed Software provided to Licensee solely for evaluation purposes (an "Evaluation License"), in the event of conflict this Section 1.b shall prevail over any other provisions set forth in this Agreement. An Evaluation License may be used for a period of no more than thirty (30) days from the date the Licensed Software is provided to Licensee ("Evaluation Term"), unless a different period is specified in writing by Licensor. An Evaluation License may be used solely for Licensee’s internal evaluation and testing purposes on a single computer system and not for development, commercial, or production purposes. For Licensed Software subject to an Evaluation License, (i) Licensee may not reproduce or distribute the Licensed Products; and (ii) Licensee’s results of benchmark or other performance tests run on or using the Licensed Software may not be disclosed to any third party without Licensor’s prior written consent. At any time during the Evaluation Term or upon completion thereof, Licensee may, upon written notification to Licensor and payment of the applicable license fee, replace the Evaluation License with a license to use the Licensed Software that is not restricted to evaluation purposes. In the absence of such notification by Licensee, the Evaluation License shall automatically terminate at the end of the Evaluation Term, and Licensee shall return, or, if Licensor so directs, delete and destroy all such Licensed Software and provide Licensor with written confirmation of its compliance with this provision. Upon written request from Licensee, Licensor may, in its sole discretion, grant Licensee an extension in writing prior to the expiration of the Evaluation Term. Other than updates to Licensed Software provided as part of support and maintenance, Licensed Software provided by Licensor free of license fee charge shall be deemed to be provided for evaluation purposes only. Licensed Software furnished under an Evaluation License is provided without any contractual obligation of maintenance and support by Licensor and is provided "as is" without warranties, implied or express, of any kind.
    3. Bundles/Suites. If the Licensed Software is licensed in a bundle or suite of multiple products, and the applicable Product Order specifies the License Option and license count for the bundle or suite (but not the individual product components of the bundle or suite), then each product in the bundle or suite shall share such license type and count. For example, individual products in the bundle or suite cannot be used by multiple users if only one user license is purchased (for user-based licenses) and cannot be installed on multiple devices or servers if only one device or server license is purchased (for device or server-based licenses).
  2. USE RESTRICTIONS. Except as may be otherwise specifically permitted in the applicable ALA, Licensee agrees not to, directly or indirectly:
    1. Copy, distribute or use the Licensed Software, in whole or in part (such as any portion, feature, function, or user interface) without paying Licensor the applicable fees;
    2. Use the Licensed Software as a service, or for timesharing, facilities management, outsourcing, hosting, service bureau use, or for providing other application service (ASP) or data processing services to third parties or for like purposes, or permit the use of the Licensed Software by a third party or permit access by or use for the benefit of any third party without executing a separate distribution agreement for the Licensed Software and paying Licensor the applicable required additional fees;
    3. Modify or create derivative works of the Licensed Software, or decrypt, translate, disassemble, recompile, decompile or reverse engineer the Licensed Software or attempt to do so (except to the extent applicable law specifically permits such activity, in which case Licensee must provide Licensor with detailed information regarding such activities);
    4. Alter, destroy, or otherwise remove any proprietary notices or labels on or embedded within the Licensed Software;
    5. Use the Licensed Software in a manner other than as specifically permitted in this Agreement or an ALA;
    6. Assign, sell, resell, license, rent, lease, lend, sublicense, outsource or otherwise transfer the Licensed Software to any third party, without first paying Licensor the applicable required license fees and obtaining Licensor’s prior written consent;
    7. Authorize, allow or appoint any third party to do any of the foregoing. For the avoidance of doubt, third parties include, without limitation, contractors and consultants (including contractors and consultants retained to provide services solely for the benefit of Licensee), outsourcers, Licensee’s affiliates and subsidiaries, parent companies, customers, and the public; or
    8. Publish or disclose to third parties any evaluation or benchmarking of the Licensed Software without Licensor's prior written consent.

      Notwithstanding the foregoing, Licensee may: (i) make a reasonable number of archival back-up copies of the Licensed Software and (ii) make a reasonable number of copies of the Documentation. Licensee shall reproduce all copyright and other proprietary rights notices appearing in or on the Licensed Products, including notices of all third party suppliers.

  3. TERM OF LICENSE. This Agreement and the license term for the Licensed Software granted herein is perpetual, unless a subscription/term license has been purchased by Licensee (in which case the license term shall be set forth in the Product Order or ALA), and is subject to earlier termination as provided in this Section 3. If Licensee has purchased a subscription/term license, such license shall automatically terminate upon expiry of such subscription/term, unless earlier terminated under this Section 3. Licensor may terminate this Agreement, along with any or all licenses then in effect with Licensee, immediately by giving Licensee written notice of termination in the event that (i) Licensee breaches any term or condition of this Agreement and fails to remedy such breach within ten (10) days of receipt of Licensor’s notice detailing such breach; (ii) Licensee becomes insolvent, has a receiver appointed, or files for or has filed against it, liquidation, bankruptcy or analogous proceedings; or (iii) Licensee infringes or misappropriates the intellectual property rights of Licensor. Termination shall be without prejudice to any other rights or remedies Licensor may have. In the event of any termination, Licensee’s license(s) to install, access or use the Licensed Software will immediately terminate, and Licensee shall destroy and erase all copies of such Licensed Software in its possession or control and provide written certification to Licensor that it has complied with this provision. Early termination of this Agreement shall not entitle Licensee to any refund or reimbursement of any previously paid fees. The rights and obligations of the parties contained in Sections 3 (Term of License), 6 (Disclaimer of Warranty), 7 (Limitation of Liability), 8 (High Risk Uses), 9 (Ownership), 10 (Third Party Software and Components), 11 (Notice to U.S. Government End Users), 12 (License Fees and Payment Terms), 13 (Audits), 15 (Privacy and Use of Licensee Information),16 (Licensee Trademark and Feedback) and 17 (Miscellaneous) will survive the termination or expiration of this Agreement.
  4. SUPPORT AND MAINTENANCE. Licensee is not entitled to any updates to the Licensed Software, unless Licensee purchases maintenance and support services pursuant to Licensor’s then-current applicable standard maintenance and support agreement, which can be found at https://www.microfocus.com/support-and-services/maintenance-and-support-agreements/ or can be provided by Licensor at Licensee’s request. Maintenance and support services (including, but not limited to, any new versions, bug fixes, and patches) provided by Licensor will be subject to such agreement. Where Licensee purchases maintenance and support for any Licensed Software, Licensee hereby agrees to purchase or keep current on such maintenance and support services for all of Licensee’s licensed units of such Licensed Software product, regardless of License Option.
  5. LIMITED WARRANTY. Licensor warrants for the Warranty Period that: (i) if the Licensed Software is supplied via media, the media will be free from defects in materials or workmanship under normal use, and (ii) the copy of the Licensed Software delivered to Licensee substantially conforms in all material respects to the Documentation. Licensee’s sole and exclusive remedy for any defective media supplied by Licensor shall be Licensor’s repair or replacement of such defective media free of charge, provided that the defective media is returned to Licensor during the Warranty Period. During the Warranty Period, Licensee’s sole and exclusive remedy for not meeting part (ii) of the above warranty shall be the repair or replacement of the Licensed Software by Licensor free of charge so that it substantially conforms to the Documentation or, if Licensor reasonably determines that such remedy is not economically or technically feasible, Licensee shall be entitled to a full refund of the license fee and any maintenance fee paid for such Licensed Software. Upon such refund, Licensee’s license to use such Licensed Software will immediately terminate. The warranties set forth in this Section 5 shall not apply if the defects in the Licensed Software or media result from: (a) failure to use the Licensed Software in accordance with the Documentation, this Agreement or ALAs; (b) the malfunctioning of Licensee’s equipment or network; (c) accident, neglect, or abuse; (d) service by any unauthorized person; (e) other software used by Licensee and not provided by Licensor, or for which the Licensed Software is not designed or licensed for such use; (f) Third Party Software that is not a Third Party Component; (g) any other cause occurring after initial delivery of the Licensed Software or media to Licensee, unless caused directly by Licensor. Licensor has no responsibility for any claims made outside of the Warranty Period. The foregoing warranty shall not apply to any free-of-charge Licensed Software or updates provided under support and maintenance. THE FOREGOING WARRANTIES DO NOT APPLY, AND LICENSOR DISCLAIMS ALL WARRANTIES, WITH RESPECT TO ANY THIRD PARTY SOFTWARE THAT IS NOT A THIRD PARTY COMPONENT. The warranties set forth in this Section 5 will not apply and will become null and void if Licensee materially breaches any provision of this Agreement.
  6. DISCLAIMER OF WARRANTY. EXCEPT FOR THE LIMITED WARRANTY SET FORTH IN SECTION 5, THE LICENSED PRODUCTS ARE PROVIDED TO LICENSEE "AS-IS" WITHOUT WARRANTY OF ANY KIND. LICENSOR DOES NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE LICENSED SOFTWARE WILL MEET LICENSEE’S REQUIREMENTS, THAT OPERATION WILL BE UNINTERRUPTED, ACHIEVE ANY INTENDED RESULT, BE COMPATIBLE, OR WORK IN COMBINATION WITH ANY OTHER SOFTWARE, APPLICATIONS, OR SYSTEMS, MEET ANY PERFORMANCE OR RELIABILITY STANDARDS, OR BE ERROR FREE, OR THAT ANY ERRORS OR DEFECTS CAN OR WILL BE CORRECTED. EXCEPT AS SET FORTH HEREIN AND TO THE EXTENT PERMITTED BY LAW, ALL OTHER WARRANTIES WITH RESPECT TO THE LICENSED PRODUCTS, WHETHER EXPRESS OR IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, QUALITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, AND WARRANTIES THAT MAY ARISE OUT OF COURSE OF DEALING, COURSE OF PERFORMANCE, USAGE, OR TRADE PRACTICE ARE EXPRESSLY DISCLAIMED BY LICENSOR AND ITS THIRD-PARTY SUPPLIERS AND AFFILIATES. LICENSEE ACKNOWLEDGES THAT LICENSEE IS RESPONSIBLE FOR THE SELECTION OF THE LICENSED SOFTWARE TO ACHIEVE LICENSEE’S INTENDED RESULTS AND FOR THE INSTALLATION AND/OR USE OF, AND RESULTS OBTAINED FROM, THE LICENSED SOFTWARE.
  7. LIMITATION OF LIABILITY.
    1. Aggregate Cap. IN NO EVENT SHALL ANY LIABILITY OF LICENSOR OR ITS AFFILIATES OR ANY OF ITS OR THEIR RESPECTIVE LICENSORS OR SERVICE PROVIDERS UNDER OR IN CONNECTION WITH THIS AGREEMENT EXCEED, IN THE AGGREGATE, THE AMOUNTS PAID BY LICENSEE FOR THE LICENSED SOFTWARE AND THE INITIAL PERIOD OF MAINTENANCE AND SUPPORT GIVING RISE TO THE APPLICABLE CLAIM.
    2. Waiver of Liability. IN NO EVENT SHALL LICENSOR OR ITS AFFILIATES OR ANY OF ITS OR THEIR RESPECTIVE LICENSORS OR SERVICE PROVIDERS BE LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR SIMILAR DAMAGES, LOSS OF PROFITS, BUSINESS, DATA, OR PROGRAMS (INCLUDING, BUT NOT LIMITED TO, THE COST OF RECOVERING OR REPLACING SUCH DATA OR PROGRAMS), LOSS, DAMAGE OR ANY COSTS DUE TO INTERRUPTION, DELAY, OR INABILITY TO USE THE LICENSED SOFTWARE, WHETHER ARISING OUT OF OR IN CONNECTION WITH THIS AGREEMENT, EVEN IF INFORMED OF THE POSSIBILITY OF SUCH DAMAGES IN ADVANCE.
    3. Scope. THE LIMITATIONS AND EXCLUSIONS OF THIS SECTION 7 APPLY TO ALL CAUSES OF ACTION, INCLUDING, WITHOUT LIMITATION, BREACH OF CONTRACT, BREACH OF WARRANTY, NEGLIGENCE, STRICT LIABILITY, MISREPRESENTATION AND OTHER TORTS. THESE LIMITATIONS AND EXCLUSIONS APPLY COLLECTIVELY TO LICENSOR, ITS PARENTS, AFFILIATES, AND SUBSIDIARIES AND EACH OF THEIR RESPECTIVE EMPLOYEES, CONTRACTORS, AND SUPPLIERS. NOTWITHSTANDING THE FOREGOING, NOTHING IN THIS SECTION 7 EXCLUDES LIABILITY FOR WILLFUL MISCONDUCT OR FRAUDULENT MISREPRESENTATION.
    4. Exclusive Remedy. LICENSEE’S REMEDIES IN THIS AGREEMENT ARE LICENSEE’S EXCLUSIVE REMEDIES. LICENSEE AGREES THAT, IN ENTERING INTO THIS AGREEMENT, IT DID NOT RELY ON ANY REPRESENTATIONS (WHETHER WRITTEN OR ORAL) OF ANY KIND OTHER THAN THOSE EXPRESSLY SET OUT IN THIS AGREEMENT.
    5. Essential Purpose. LICENSEE FURTHER ACKNOWLEDGES THAT THE LIMITATIONS AND EXCLUSIONS OF LIABILITY IN THIS SECTION 7 APPLY TO THE FULLEST EXTENT PERMITTED BY LAW AND ARE AN ESSENTIAL ELEMENT OF THIS AGREEMENT AND THAT, IN THE ABSENCE OF SUCH LIMITATIONS AND EXCLUSIONS, THE PRICING AND OTHER TERMS AND CONDITIONS SET FORTH HEREIN WOULD BE SUBSTANTIALLY DIFFERENT. THE LIMITATIONS AND EXCLUSIONS SET FORTH IN THIS SECTION 7 SHALL APPLY EVEN IF THE LICENSEE’S REMEDIES UNDER THIS AGREEMENT FAIL OF THEIR ESSENTIAL PURPOSE.
    6. Free Software. IF LICENSOR PROVIDES LICENSEE WITH ANY LICENSED SOFTWARE FREE-OF-CHARGE OR UNDER AN EVALUATION LICENSE, TO THE EXTENT PERMITTED BY LAW, LICENSOR SHALL NOT BE RESPONSIBLE FOR ANY LOSS OR DAMAGE TO LICENSEE, ITS CUSTOMERS, OR ANY THIRD PARTIES CAUSED BY THE LICENSED SOFTWARE THAT IT MAKES AVAILABLE TO LICENSEE.
  8. HIGH RISK USES. The Licensed Software is not fault tolerant, nor designed, manufactured, or intended for use in hazardous environments requiring fail-safe performance (including, without limitation, the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life support machines, or weapons systems) in which failure of the Licensed Software could lead directly or indirectly to death, personal injury, or severe physical or environmental damage. Licensor and its suppliers shall have no liability for any use of the Licensed Software in any high-risk situations.
  9. OWNERSHIP. The Licensed Products are provided under license, and not sold, to Licensee. The only rights in the Licensed Products are the licenses expressly stated in this Agreement and no other rights are implied or granted by estoppel. Licensor (and its affiliates) and its and their licensors and third party suppliers retain ownership of, and reserve all rights in and to, the Licensed Products, including all copies thereof, and all intellectual property rights arising out of or relating to the Licensed Products. Licensee shall use reasonable efforts to safeguard the Licensed Products (including all copies thereof) from infringement, misappropriation, theft, misuse, or unauthorized access. Licensee shall promptly notify Licensor if it becomes aware of any infringement or misappropriation of the Licensed Products and shall fully cooperate with Licensor, at Licensor’s expense, in any legal action taken by Licensor to enforce its intellectual property rights.
  10. THIRD PARTY SOFTWARE AND COMPONENTS. The Licensed Software may come with or require Third Party Software that Licensee shall license directly from the third party licensor pursuant to such third party’s terms and conditions and not this Agreement. Additionally, some Licensed Software may include certain Third Party Components and open source software. Such open source software and Third Party Components may also be loaded on the Licensed Software media. Third Party Components are licensed to Licensee under this Agreement; open source software is licensed pursuant to the applicable open source license. To the extent applicable, information about the open source software may be found (i) in a file accompanying the applicable Licensed Software or (ii) in the Documentation or ALA. Licensee shall not directly access any Third Party Components other than with or as part of the Licensed Software. Licensee agrees that to the extent required by a third party licensor or supplier of a Third Party Component, that third party licensor or supplier is an intended third party beneficiary of this Agreement as necessary to protect intellectual property rights in the Licensed Software and limit certain uses thereof.
  11. NOTICE TO U.S. GOVERNMENT END USERS. The Licensed Products are deemed to be "Commercial Items," as defined at 48 C.F.R. §2.101, consisting of "Commercial Computer Software" and "Commercial Computer Software Documentation," as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with such sections, the Licensed Products are licensed to U.S. Government end users (i) only as Commercial Items, and (ii) with only those rights as are granted pursuant to this Agreement.
  12. LICENSE FEES AND PAYMENT TERMS. Licensee agrees to pay the applicable license fees for the Licensed Products within thirty (30) days of the date of invoice or such other date as agreed in writing by the parties. Software license fees are non-refundable, except as provided in Section 5 above, and shall be paid without any deduction or tax withholding. Software License fees are exclusive of any applicable transportation charges, sales, use, value added tax, and other applicable taxes and duties, and all such amounts shall be paid or reimbursed by Licensee. Licensee shall be liable for all outstanding past due amounts, which shall accrue interest at the rate of 1.5% per month compounded or, if lower, the maximum rate allowed by applicable law, and any collection costs associated with the collection of any past due amounts.
  13. AUDITS. Licensor or an Auditor (as defined below) has the right to verify Licensee’s compliance with the licenses issued under Product Orders, the applicable ALAs and this Agreement (please see Micro Focus License Compliance Charter at http://supportline.microfocus.com/licensing/licVerification.aspx, which can also be provided by Licensor at Licensee’s request). Licensee agrees to:
    1. Recordkeeping. Keep, and upon Licensor’s request, provide records, sufficient to certify Licensee’s compliance with this Agreement based on the applicable License Option(s) (including applicable license metric and other terms and conditions) for the Licensed Software, which may include but are not limited to, serial numbers, license keys, logs, the location, model (including quantity and type of processor) and serial number of all machines on which the Licensed Software is installed or accessed or from which the Licensed Software can be accessed, the names (including corporate entity) and number of users accessing or otherwise able to access the Licensed Software, metrics, reports, copies of the Licensed Software (by product and version), and network architecture diagrams as they may relate to Licensee’s licensing and deployment of the Licensed Products and associated support and maintenance;
    2. Questionnaire. Within seven (7) days of Licensor’s request, Licensee shall furnish to Licensor or its designated independent auditor ("Auditor") a completed questionnaire provided by Licensor or Auditor, accompanied with a written statement signed by a director of Licensee certifying the accuracy of the information provided; and
    3. Access. Provide representatives of Licensor or Auditor any necessary assistance and access to records and computers to allow an inspection and audit of Licensee’s computers and records, during Licensee’s normal business hours, for compliance with licenses, the applicable ALAs, and this Agreement, and fully cooperate with such audit.
    4. Non-Compliance. In the event that Licensee has, or at any time has had, unlicensed installation, use of, or access to the Licensed Software or has otherwise breached this Agreement or an ALA (a "Non-Compliance"), without prejudice to any other rights or remedies Licensor may have, including, without limitation, injunctive relief, Licensee shall, within thirty (30) days’ notice of such Non-Compliance to Licensee, purchase sufficient licenses and/or subscriptions and associated support and maintenance to cure the Non-Compliance, by paying Licensor’s current (as of the date of such additional purchase) list license fees and 12-month support and maintenance fees to Licensor for such additional licenses, plus Licensor’s current (as of the date of such additional purchase) list term license and support and maintenance fees and interest (compounded at 1.5% monthly or the maximum rate permitted by applicable law if lower) for such additional licenses for the time period from the commencement of the Non-Compliance until payment of the aforementioned fees, with interest payable even if an invoice was not issued at the time the Non-Compliance occurred. For purposes of the foregoing, "list" shall mean Licensor’s full list price as set forth in Licensor’s standard price list that is current as of the commencement of the audit without any volume or other discount. If Licensee’s Non-Compliance results in an underpayment of license fees of 5% or greater, Licensee shall also reimburse Licensor for the reasonable cost of such audit in addition to other amounts due. In the event of a dispute related to a Non-Compliance, Licensor shall have the right to collect from Licensee its reasonable costs and attorneys' fees incurred in enforcing this Agreement.
  14. RELATED SERVICES. Licensee shall be responsible for obtaining and installing all proper hardware and other third party support software (including operating systems) for the proper installation and implementation of the Licensed Software. In the event that Licensee retains Licensor to perform any services with respect to the Licensed Software (for example: installation, implementation, maintenance, consulting, or training services), Licensee and Licensor agree that such services shall be provided at Licensor’s then- current standard terms, conditions, and rates for such services unless otherwise agreed in writing by Licensor.
  15. PRIVACY AND USE OF LICENSEE INFORMATION.
    1. Responsibility and Compliance with Laws. Licensee is solely responsible for and assumes all liability with respect to its own collection, processing, storage, and transfer of any user data, including, but not limited to, personally identifiable information and personal health and financial information (collectively, "Personal Information"). Licensee shall be solely responsible for notifying its users of proper use of such data. Each party is responsible for complying with its respective obligations under all applicable laws, regulations, and industry standards regarding data collection and data privacy applicable for the use of the Licensed Software by the relevant party.

      Licensee shall not provide any Personal Information to Licensor for processing by Licensor on behalf of Licensee, unless otherwise agreed by the parties in writing in an applicable transaction document with applicable privacy terms. If the parties agree that processing Personal Information is necessary for the performance of this specific transaction, and when such Personal Information processing falls within the scope of the General Data Protection Regulation (EU) 2016/679 ("GDPR"), before any Personal Information is made available to Licensor, the parties agree that Licensee will be the data controller and Licensor will be the data processor, and when Licensor is processing Personal Information on behalf of Licensee, such processing shall be governed by terms that comply with Article 28 of the GDPR including standard contractual clauses to be included in such transaction document.

      Licensor will not have access to protected health information unless the parties have an executed business associate agreement in place for this transaction. Licensee is solely responsible for assessing the Licensed Product or any related product or service for compliance with any industry requirements applicable to Licensee.

    2. Consent to Use of Licensee Information. To the extent required or permitted by law, Licensee hereby expressly consents to (i) receiving information from Licensor from time to time advertising Licensor’s products; (ii) the use of Licensee’s name in Licensor customer lists, promotional materials, and press releases; and (iii) the collection and use of information about the computer system on which the Licensed Software is installed (e.g. product version, serial number) for internal security and licensing purposes. Further information about Licensor’s processing of personally identifiable data is available at https://www.microfocus.com/about/legal/#privacy (click "Privacy Notice" tab) or can be provided by Licensor at Licensee’s request.
    3. Other Use of Licensee Information. To the extent required or permitted by law, and notwithstanding the terms in Section 15.a, Licensor may also process personally identifiable information of Licensee and Licensee’s users (i) in order to comply with a legal obligation to which Licensor is subject; (ii) as is necessary for the performance of this Agreement; and (iii) where necessary for the purposes of Licensor’s legitimate interests, except where such interests are overridden by the interests or fundamental rights and freedoms of the Licensee or Licensee’s users which require protection of personally identifiable information.
  16. LICENSEE TRADEMARK AND FEEDBACK. Licensor may use Licensee’s name and logo for business development and marketing purposes, including, but not limited to, online and printed sales and marketing materials. Any other use of Licensee’s name or logo, or a description of Licensee’s use of the Licensed Software, shall be subject to Licensee’s prior consent. Any suggestions, ideas for modifications, enhancements, and other feedback from Licensee regarding the Licensed Software provided at any time (collectively, the "Feedback"), including (but not limited to) all intellectual property rights in and to such Feedback, shall be owned exclusively by Licensor. Licensee hereby assigns all right, title and interest in and to such Feedback and all the intellectual property rights therein to Licensor, without the necessity of any further consideration. To the extent any Feedback cannot be assigned to Licensor, Licensee hereby grants to Licensor a perpetual, irrevocable, exclusive, worldwide, royalty-free, fully paid up license, with the right to sublicense through multiple tiers to use, make, sell, distribute, execute, adapt, translate, reproduce, display, perform, modify, create derivative works of and otherwise exploit the Feedback in any manner.
  17. MISCELLANEOUS.
    1. Assignment. Licensor may assign this Agreement, including any rights or obligations under the Agreement (in whole or in part) to a parent or an affiliate. Licensee may not assign or transfer this Agreement or any of its rights or duties hereunder, including (but not limited to) by merger, acquisition by any entity of all or substantially all of Licensee’s stock or assets, change of control, operation of law, or otherwise, without the prior written consent of Licensor and payment by Licensee of the applicable assignment fee. Any attempted assignment not in accordance with this Section shall be null and void.
    2. Governing Law. If Licensee is located in North America, the laws of the State of California govern this Agreement and the licenses granted hereunder, and the parties hereto consent to the exclusive jurisdiction of the State and Federal courts of the State of California in any action based on this Agreement or the Licensed Software hereunder or any License Option under an ALA. Each party waives any right it may have to object to such venue, including objections based on personal jurisdiction or forum non conveniens (inconvenient forum). The parties agree that the Uniform Computer Information Transaction Act or any version thereof, adopted by any state, in any form ("UCITA"), shall not apply to this Agreement. To the extent that UCITA is applicable, the parties hereby opt out of the applicability of UCITA pursuant to the opt-out provision(s) contained therein. If Licensee is located in France, Germany or Japan, this Agreement is governed by the laws of the country in which Licensee is located. In the rest of the world the laws of England govern this Agreement. In each case, the applicable law shall apply without regard to conflict of laws provisions thereof, and without regard to the United Nations Convention on the International Sale of Goods. Other than for North American transactions, this Agreement, the licenses granted hereunder, and the parties hereto, shall be subject to the exclusive jurisdiction of the courts of the country determining the applicable law as aforesaid.
    3. Export Control. This Agreement may be subject to export control laws, regulations, and other restrictions of the United States (including, but not limited to, the U.S. Export Administration Regulations (the "EAR")), United Kingdom, or the European Union regarding export or re-export of computer software and technology. Licensee agrees to comply with all applicable export control laws, regulations, and restrictions, including the EAR, where applicable.
    4. Entire Agreement. The applicable Product Order and this Agreement including the applicable ALA, constitutes the complete and exclusive statement of agreement between the parties relating to the license for the Licensed Products and supersedes all prior proposals, communications, purchase orders, and agreements (including, without limitation, Other Agreements), without need for a mutually executed amendment to any such Other Agreement. Any conflicting terms and conditions shall be resolved according to the following order of precedence: the applicable Product Order, the applicable ALA, and then this Agreement in all other respects.
    5. Amendment. No representation, supplement, modification, or amendment of this Agreement will be binding on either party unless executed in writing by duly authorized representatives of both parties (excluding any distributor or reseller of Micro Focus) to this Agreement.
    6. Waiver. No waiver of any right under this Agreement will be effective unless in writing and signed by authorized representatives of both parties (excluding any distributor or reseller of Licensor). No waiver of any past or present right arising from any breach or failure to perform will be deemed to be a waiver of any future right arising under this Agreement.
    7. Severability. If any provision in this Agreement is invalid or unenforceable, that provision will be construed, limited, modified or, if necessary, severed, to the extent necessary, to eliminate its invalidity or unenforceability, and the other provisions of this Agreement will remain unaffected.
    8. No Reliance. Each party acknowledges that in entering into this Agreement it has not relied on any representations, agreements, warranties or other assurances (other than those repeated in this Agreement) and waives all rights and remedies which but for this Section 17 would be available to it.

Micro Focus EULA (1 November 2019)

Parent topic: Getting Started


Additional License Authorizations for Micro Focus Enterprise Extension for Visual Studio Code

Full details of the terms and conditions of usage can be found at: software.microfocus.com/legal/software-licensing

This Additional License Authorizations document (“ALA”) set forth the additional specific software license terms that govern the authorized use of the software products specified below, and are part of the applicable agreement (i.e., Micro Focus End User License Agreement; and/or any separate agreement that grants Licensee a license to such products (e.g., Customer Portfolio Terms or other Master Agreement); and/or Quotation) (the “Applicable Agreement”). Capitalized terms used but not defined herein shall have the meanings set forth in the Applicable Agreement.

Products covered

Products | E-LTU or E-Media available* | Non-production software class | Term License Non-production software class (if available)**
Micro Focus COBOL Extension for Visual Studio Code | Yes | Class 2 | Class 2
Micro Focus Enterprise Extension for Visual Studio Code | Yes | Class 2 | Class 2

* Any product sold as E-LTU or E-Media shall be delivered electronically regardless of any contrary designation in a purchase order.

** Additional licenses solely for non-production use may be available as specified in the Non-Production Licensing Guide found at https://software.microfocus.com/en-us/about/software-licensing depending on the non-production software class specified above. Any such non-production licenses will be subject to the Non-Production Licensing Guide and the applicable terms and conditions set forth in this ALA.

Software Specific Terms

Micro Focus Extensions for Visual Studio Code

This Licensed Software may be used solely with Visual Studio Code. Additional functionality in the Licensed Software may be available if used with a validly licensed copy of certain Licensor software products. In such event, the license terms applicable to such software products shall continue to apply to such software and not be affected by this ALA. No support or maintenance is provided or available for this Licensed Software except where otherwise agreed by Licensor in writing.

Licensee shall not use the Licensed Software, nor reproduce or distribute any files supplied as part of the Licensed Software, in order to create a compiler, interpreter, runtime support product or any other product that is generally competitive with or a substitute for any Licensor product.

software.microfocus.com/legal/software-licensing Latest version of software licensing documents

© Copyright 2021 Micro Focus.

Parent topic: Getting Started


Editing Code

The Micro Focus 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 Code Efficiently
  • COBOL Language Server


Writing 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 editor depend on COBOL Language Server and require that the 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 Micro Focus Enterprise Developer product on the same machine. See Installation for details.

A number of advanced editing and navigation features of the Micro Focus 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.

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 right bottom corner of Visual Studio Code shows whether the COBOL Language Server is running:

  1. Click [image] in the right bottom corner of Visual Studio Code.

    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.

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


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.


Compiling

Important: This functionality requires a licensed version of a Micro Focus 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 Micro Focus 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 Core 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 products installed:
    • Micro Focus Enterprise Developer for Visual Studio
    • Micro Focus Enterprise Developer Build Tools

The Micro Focus 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 Core COBOL Projects

Prerequisites

In order for the Micro Focus Enterprise extension to work with .NET Core projects, you need the following software installed:

  • A licensed installation of one of the following Micro Focus 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 Core COBOL Project

Your .cblproj or .sln .NET Core projects and solutions must be created with Enterprise Developer for Visual Studio. The .cblproj 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,Micro Focus 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 Core COBOL Projects.

Parent topic: Compiling
Related tasks
Debugging .NET Core COBOL Projects


Compiling Eclipse Projects

You can use the Micro Focus 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.

The extension auto-generates build tasks for each .cobolBuild file found.

This has the following requirements:

  • A licensed version of one of the following products:
    • Micro Focus Enterprise Developer
    • Micro Focus Enterprise Developer Build Tools

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

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

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

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.

Parent topic: Compiling
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.

Micro Focus recommends that you define your own custom shell tasks to invoke the build script. The Micro Focus 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 Micro Focus 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 Micro Focus 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.

Debugging features

Visual Studio Code provides the Debug console panel 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
  • Advanced Debug Launch Configurations
  • Watchpoints
  • Program Breakpoints
  • Debugging the Current File
  • PL/I Data Breakpoints
  • PL/I Conditions and Signals
  • Attach to Process
  • Debugging .NET Core COBOL Projects
  • Just-In-Time Debugging
  • Debugging Using the Remote Development Extensions
  • Debugging applications that run on Ubuntu
  • Debug Native COBOL applications Running in an Enterprise Server


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. This is how you debug your code with the default launch configuration:

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

    This shows the Task Picker with the available debugging tasks:

  3. 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 Micro Focus 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.

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

  5. Select the launch configuration, COBOL (native): Launch or PL/I: Launch, and click [image] (Start Debugging).
    Debugging features in Visual Studio Code
  6. Use the commands in the Debug widget to step through the code.
    The Visual Studio Code debug widget
  7. Use the available views to watch how variables change.
  8. 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.

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


Advanced Debug Launch Configurations

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

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

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

    You can add one of the following configurations - COBOL (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.For PL/I code, the additional configurations are - 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, respectively.

    Optionally, you can add more settings to these as required.

Some of the settings you can specify are:

  • "args": [] - command line arguments for the program.
  • "cwd": "${workspaceFolder}" - current working directory. This is set to the workspace folder, by default.
  • "env": [ {"name": "", "value": "" }] - specify any environment variables as required.
  • "is64bit": true - if you want to debug a 64-bit application. This is set to true by default on Linux.
  • "program": "${workspaceFolder}/<insert-program-name-here>" - specify an executable or a core dump file.
  • "remoteDebug" - specify any remote debug settings. You need to have Enterprise Developer and cobdebugremote running on the remote machine:
                "remoteDebug": {
                "machine": "machine name or IP",
                "port": nn
            }

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

                "pathMappings": [
              {
                    "remote": "remote-path",
                    "local": "local-path"}
            ],
  • "symbolSearchPaths": [] - specify the location of the .idy files (for COBOL code) or .stb files (for PL/I) code.
  • "stopOnEntry": true - the debugger stops on the first line of debuggable code.
  • "waitForAttachment":
        "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.

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 Micro Focus Enterprise Developer.

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 Micro Focus 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. You can toggle this watchpoint on and off by right-clicking and selecting Toggle Enable Watchpoint.

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. Right-click the condition, and then add one or both of the following:
    • Edit Condition Expression: a conditional expression, such as variable EQUALS value. (Bear in mind that 'Breaks when' is prefixed to your expression to form the complete expression. Also, there is no syntax validation of your expression; if it is syntactically incorrect, it just won't work.)
    • Edit hit count: this represents the number of times that the area of memory is updated; click the current hit count criteria and select from the list of criteria displayed, and then enter the appropriate value.

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

  3. You can toggle the conditions on and off by selecting 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

Important:
  • This functionality requires a licensed version of a Micro Focus 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, right-click the required program breakpoint, and click Toggle Enable Program Breakpoint to disable it.

To delete a program breakpoint:

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


Debugging the Current File

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

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}"
            ]
        }
    ]
}
Parent topic: Debugging


PL/I Data Breakpoints

Important:
  • This functionality requires a licensed version of a Micro Focus 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 Micro Focus 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 Micro Focus 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


Debugging .NET Core COBOL Projects

Prerequisites

In order for the Micro Focus Enterprise extension to work with .NET Core projects, you need the following software installed:

  • A licensed installation of one of the following Micro Focus 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 Core 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 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 Core COBOL project

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

  1. See Compile .NET Core 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/netcoreapp3.1/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 Core COBOL Projects


Just-In-Time Debugging

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

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 Micro Focus COBOL or Enterprise 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 extensions folder is micro-focus.amc.mfcobol-<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


Debugging Using the Remote Development Extensions

Important: This functionality requires a licensed version of a Micro Focus 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 ForwardX11 to yes

    ForwardX11Trusted 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 applications that run on Ubuntu

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

By default, on Ubuntu, 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


Debug Native COBOL applications Running in an Enterprise Server

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

You can debug a native COBOL application which runs under Micro Focus 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


Scenarios

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

  • Remote Development
  • Accessing a Micro Focus COBOL Product Running in a Container


Remote Development

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

A common scenario for when you can use Visual Studio Code with the Micro Focus 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 Micro Focus 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 Micro Focus 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 Micro Focus COBOL 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.
  • Micro Focus 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 Micro Focus COBOL 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 Micro Focus COBOL environment on it. There are no Micro Focus COBOL 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 Micro Focus COBOL extension installed yet.

Install the Micro Focus Enterprise extension

You are now going to install Micro Focus 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 Micro Focus 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 Micro Focus 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 Micro Focus 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 Micro Focus 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 Micro Focus 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 Micro Focus 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 Micro Focus COBOL Product Running in a Container

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

The following demonstration shows how you can use Visual Studio Code with the Micro Focus Enterprise extension to edit, compile and debug a COBOL applications in a Docker container that has Micro Focus 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 any Micro Focus products 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 Micro Focus 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 Micro Focus COBOL 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 Micro Focus 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": [
        "Micro-Focus-AMC.mfcobol"
    ]

}

    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 Micro Focus COBOL 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 Micro Focus COBOL product is installed in the container.

    The last part that has Micro-Focus-AMC.mfcobol 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 Micro Focus COBOL extension

The .devcontainer file includes the instructions to download and install the Micro Focus 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


Help With the Extension

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

For help with functionality in the extension that relies on your licensed Micro Focus Enterprise Developer product, you can also contact Micro Focus Customer Care.


Copyright and Disclaimer

© Copyright 2022 Micro Focus or one of its affiliates.

The only warranties for this product and any associated updates or services are those that may be described in express warranty statements accompanying the product or in an applicable license agreement you have entered into. Nothing in this document should be construed as creating any warranty for a product, updates, or services. The information contained in this document is subject to change without notice and is provided "AS IS" without any express or implied warranties or conditions. Micro Focus shall not be liable for any technical or other errors or omissions in this document. Please see the product's applicable end user license agreement for details regarding the license terms and conditions, warranties, and limitations of liability.

Any links to third-party Web sites take you outside Micro Focus Web sites, and Micro Focus has no control over and is not responsible for information on third-party sites.

This product includes software developed by Computing Services at Carnegie Mellon University (http://www.cmu.edu/computing/).

2022-12-14