IBM Z Open Editor is an extension for Visual Studio Code that provides language support for the IBM® Enterprise COBOL, PL/I, and JCL languages.
This extension provides language support for the IBM Enterprise COBOL 6.2 and PL/I 5.2 programming languages for z/OS®. This also includes capabilities for embedded statements for CICS 5.5, IMS 15.1.0 and SQL DB2 for z/OS 12.1. Earlier versions of any of these components will also work.
IBM Z Open Editor realizes its language support by implementing fully functional language servers together with additional editor enhancements that enable mainframe developers to utilize features such as:
- Real-time syntax checking and highlighting while you type
- Problems view with all syntax errors and (in COBOL) unreachable code
- Outline view and outline search
- For both variables and paragraphs:
- Declaration hovers
- Peek definition
- Go to definition
- Find all references
- Code and variable completion
- Code template snippets
- Finding and navigating references
- Previewing of included copybooks and include files
- Navigate to copybooks and include files
- Refactoring such as "rename symbol"
- Search and replace refactoring across multiple program files
For the Job Control Language (JCL), the extension provides simple syntax highlighting.
To learn more about the IBM Z Open Editor extension's capabilities, we suggest that you walk through our full documentation and try it with the example repository provided on GitHub.
To interact with z/OS, we recommend installing the Zowe VS Code Extension. This extension can be used to edit COBOL and PL/I files opened on z/OS MVS™ and USS using the Zowe extension's Data Sets and USS views. It can even run JCL and let you browse job spool files.
- Privacy notice
- Prerequisites
- Configuring Java
- COBOL and PL/I Language Server Protocol capability examples
The IBM Z Open Editor is provided free of charge, but we ask you to provide us feedback via the various means available such as submitting an issue in our GitHub repository, providing review in the VS Code Marketplace as well as keeping the built-in telemetry and crash reports enabled.
This editor uses Microsoft VS Code's Telemetry solution that collects telemetry data, which is used to help understand how to improve the product. While we appreciate the insights this data provides, we also know that not everyone wants to send usage data and you can disable telemetry as described in Disable Telemetry Reporting. You can also read IBM's General Privacy Statement to learn more about our policies.
This current release of IBM Z Open Editor will collect anonymous data for the following events:
- Activation of this VS Code extension
- Opening files of a specific language such as COBOL, PL/I, JCL
- Deactivation of this VS Code extension
Each such event is logged with the following information:
- Event time
- Operating system and version
- Country or region
- Anonymous user and session ID
- Version numbers of Microsoft VS Code and IBM Z Open Editor
- Z programming language used
Review the IBM Z Open Editor License Agreement, Third Party Notices, and terms and conditions for separately licensed code before downloading.
Here are the prerequisites for installing this extension in Visual Studio Code:
-
IBM Java™ version 8 or later - 64 bit: The COBOL and PL/I language servers included in this extension are implemented in Java. Therefore, you need to install and configure a 64-bit Java runtime in order to start it successfully.
- The preferred Java SDK to use is IBM Java 8.
- Alternatively, you can use Oracle Java SDK 8 and any later version of Oracle Java or OpenJDK.
Various settings are provided to configure how the extension uses Java. See the Configuring Java section below for more details.
-
(Optional) Git: To use the features that involve Git, you must install Git and have it available in your system path so that VS Code can display it. On Macs, Git comes out of the box. On Linux, you can install Git with your distribution's package manager. On Windows, you can get Git from https://git-scm.com.
-
(Optional) Zowe CLI 2.22 and the Zowe VS Code extension 0.24.1 or later: To make use of Zowe to open and edit files directly from z/OS MVS or USS, you need Zowe client software and z/OSMF configured. For more information, see Installing Zowe CLI and VS Code Extension for Zowe. Once installed, you must create a Zowe CLI user profile so that data sets can be found and accessed.
If you are looking for some COBOL, PL/I, or JCL code that you can use to explore the editor features then you can use samples that we maintain on Github. Assuming that you have Git installed, create a work directory somewhere on your machine and clone the sample repository:
git clone https://github.com/IBM/zopeneditor-sample.gitThen once you finished installing the IBM Z® Open Editor extension open the directory zopeneditor-sample using the File > Open... menu.
The COBOL and PL/I language servers utilized by IBM Z Open Editor were implemented using the Java programming language. Therefore, a Java Runtime is required to be available in the program path to start in VS Code. The IBM Z Open Editor extension utilizes VS Code Settings properties, which can be added to VS Code workspace or user settings, to configure which and how Java should be used. These settings allow you to select the specific installation of Java to pick, in case you have several installations, as well as set parameters such as how much memory you want the extension to use. You can make the settings by editing the settings.json file for your workspace or in the user preferences settings directly.
The language server clients running in the IBM Z Open Editor VS Code extension try looking in different places to find a matching Java. By default, it looks for Java using the JAVA_HOME environment variable if no settings were provided for the user to the current workspace. If that was not defined, it finds Java in the user's PATH. If both the JAVA_HOME environment variable and user's PATH do not contain a valid Java installation, you will see an error message that shows the language server for either COBOL or PL/I might not be started.
To fix the problem, either provide the missing value or define a Settings entry in your VS Code user or workspace settings. The setting always has precedence over the other two options described above. In other words, it tries to use that Java installation first. This allows you to specify a different Java for IBM Z Open Editor other than the default of your computer.
The configuration for the alternative JAVA_HOME will accept a path to the Java SDK, for example:
On Mac:
"zopeneditor.JAVA_HOME": "/Library/Java/JavaVirtualMachines/jdk1.8.0_181.jdk/Contents/Home"On Windows:
"zopeneditor.JAVA_HOME": "C:\\Program Files\\Java\\jdk1.8.0_171"By default, the language server clients that start the language servers for COBOL or PL/I allocate a maximum of 512 MB of memory for each. In other words, they start using much less memory in the beginning, but you might run out of memory when working on large program files; or your computer might not support such a large amount of memory in the first place. To have more flexibility in how much memory the language servers are allowed to allocate, the following VS Code Setting is provided to specify the maximum value. When you use both COBOL and PL/I, you need to double the amount specified.
"zopeneditor.server.memoryAllocation": 1024You can use this view to:
- Expand and collapse sections such as Division Headings, Section Headings, and Variable Group Names in the Outline View.
- Recognize includes, procedures, loops quickly via the icons located by the various items.
- Go to a wanted location in the code by clicking that section header in the view.
- Sort by Position, Name, or Type.
Searching for identifiers within the outline by pressing Ctrl+Shift+O (PC) or Cmd+Shift+O (Mac) within the Editor window.
To see the working storage definition or DCL definition and the parent group of a variable or a paragraph name, move your mouse cursor over to the variable or paragraph name.
Click on a variable or a paragraph name, right-click for menu, and choose Peek Definition. This opens a CodeLens box that shows where the variable or paragraph was defined in the code. If you use the keyboard shortcut Alt+F12 (Windows) or Option+F12 (Mac), the variable or paragraph name is only clicked once before the keyboard shortcuts are pressed. Double-click any result to go to that location in the file.
To preview the contents of a copybook or included file, move your mouse cursor over the copybook name in a COPY statement in COBOL or %INCLUDE in PL/I. To open the file in a separate editor, press Ctrl+Click (Windows) or Cmd+Click (Mac). If you have Zowe CLI installed, you can define a search path to resolve copybooks over the network against your remote MVS data sets or even USS directories (COBOL only at the moment).
Select a variable or a paragraph name, right-click for menu, and choose Peek References or use shortcut Shift+F12 (Windows and Mac). Double-click any result in the CodeLens box to go to that location in the file.
When you start typing a command, a selection list of commands and code snippets are displayed automatically or by typing Ctrl+Space depending on your preferences settings.
This feature also works for variable names defined in the program.
| Description | Windows | Mac |
|---|---|---|
| Search for identifiers within the outline | Ctrl+Shift+O |
Cmd+Shift+O |
| Show the list of available code completion | Ctrl+space |
Ctrl+Space |
| Open copybook/include files in a separate editor | Ctrl+click |
Cmd+Click |
| Change all occurrences | Ctrl+F2 |
Cmd+F2 |
| Find all references | Alt+shift+F12 |
Option+Shift+F12 |
| Peek references | Shift+F12 |
Shift+F12 |
| Go to definition | F12 |
F12 |
| Peek definition | Alt+F12 |
Option+F12 |
| Rename symbols | F2 |
F2 |