Known issues and limitations

The IBM Z® Open Editor extension has some known issues and limitations. This page provides the status of the current release. Also review the list of open issues and enhancement requests in our Github repository. It might list issues that are not yet documented here.

Java™ 17 64-Bit JRE or SDK required

If the right version of Java cannot be found in the current user's path or if no JAVA_HOME environment variable was defined, you might see error messages in the Output view of VS Code. Such errors could also be caused by other reasons such as not enough free memory for Java on your system.

Go through all the steps described in the Getting Started page for configuring Java to try out different options.

Java not found on Linux

Z Open Editor starts by searching for Java in the following locations:

• The path specified by the zopeneditor.JAVA_HOME value in your VS Code settings.
• The path specified by the java.jdt.ls.java.home value in your VS Code settings.
• The path specified by your JAVA_HOME environment variable.

After searching these locations, Z Open Editor will run commands to try and find Java on your operating system.

If your installation is not found and you see errors in the Welcome page, try specifying a path to your Java for your zopeneditor.JAVA_HOME or java.jdt.ls.java.home value in your VS Code settings or setting your system's JAVA_HOME environment variable. Ensure that you exclude the bin/java directory from your path. For more information, see Configuring Java.

Resetting Language Servers or VS Code

It might happen that the language servers provided by IBM Z Open Editor become inconsistent and do not behave as expected. For example, a language server might stop reporting syntax errors, or it cannot resolve copybooks anymore. Instead of quitting and restarting VS Code completely, you can try pressing the F1 key and type the following commands to reset one or more language servers.

• IBM Z Open Editor: Pause the COBOL Language Server: Stops the COBOL language server and restarts it when you open a COBOL file again.
• IBM Z Open Editor: Pause the PL/I Language Server: Stops the PL/I language server and restarts it when you open a PL/I file again.
• IBM Z Open Editor: Pause the Assembler Language Server: Stops the HLASM language server and restarts it when you open an HLASM file again.
• IBM Z Open Editor: Pause the REXX Language Server: Stops the REXX language server and restarts it when you open a REXX file again.
• IBM Z Open Editor: Pause the JCL Language Server: Stops the JCL language server and restarts it when you open a JCL file again.
• IBM Z Open Editor: Reload Zowe Profiles: If you have changed the password of your Zowe CLI profile that is used to load your remote include files such as copybooks, you need to run this command to refresh the Zowe profile.
• Developer: Reload Window: Restarts the current VS Code window and all of its extensions. If you have many editor windows open at the same time, you can use this command to reset just the current window in which you run the command.

Limitations for Visual Studio Code Multi-Root Workspaces

IBM Z® Open Editor supports VS Code multi-root workspaces, but there are some limits or special rules on how ZAPP files and settings are used in a multi-root workspace:

• Property Groups: the multi-root workspace can load multiple zapp files located in the top-dir of each workspace. We search for property groups in each of these zapp files in the order the workspaces are listed in the .code-workspace .code-workspace file when resolving include files.
• For user build the DBB ZAPP profile located in the workspace of the program being built is being used. The application-conf files (additional files listed in zapp profile) also need to be in the root of the workspace with the program.
• For Z Open Editor's user build, local copybooks and include files that need to be uploaded to z/OS UNIX System Services for build can be located in any other workspace of the multi-root workspace. The location of the copybooks and include files must be specified in the ZAPP file of the workspace in which these include files are located in. A ZAPP file cannot provide property groups that point to locations outside of its workspace. The exception would be using absolute path names, but those might break the ability to share the ZAPP file with other team members as they might have their files in different locations.

Limitations of using Z Open Editor with Eclipse Che and Red Hat OpenShift Dev Spaces

Almost all capabilities described in this documentation are available when you use IBM Z Open Editor with Eclipse Che or Red Hat OpenShift Dev Spaces. However, note the following limitations.

• Zowe CLI secure credentials are currently not supported with Z Open Editor on Eclipse Che and Red Hat OpenShift Dev Spaces. The Zowe Explorer setting "zowe.security.secureCredentialsEnabled": false must be used in these environments. See the section Setting up integrations to interact with z/OS > Managing credentials unsecured.

• Path names specified for property groups in ZAPP files are always case-sensitive, even if the setting "zopeneditor.enforceCaseSensitiveIncludeFileNames" is set to false. However, this setting works for the file names that get matched in the folders that match the property groups.

Language-specific features and limitations

COBOL

The following lists show the implementation status of the COBOL language server. Use these lists to check that the feature that you are looking for was implemented or is regarded as a known issue. Let us know if you have any additional issues.

Enabled features of COBOL program files

• Syntax highlighting
• Syntax errors
  • Errors are translated for different locales
• Document highlighting
• Hover
• Go to declaration
• Find all references in file and across the multiple files
• Peek references in file and across the multiple files
• Rename symbol in file and across the multiple files
• Outline view
• Code completion
• Snippets
• Copybook resolving and copybook hover support
• Document link support to open copybook by using Ctrl+Click (Windows) or Cmd+Click (Mac)
• Embedded languages support such as SQL, CICS®, and DLI
• Renumber and Unnumber sequence numbers
• Syntax highlighting support for Sequence Numbers (1-6 and 73-80 columns)
• Latest COBOL 6.4 PTF language support, up to and including the February 2024 PTF.
• Embedded Language Support for CICS 6.2 in COBOL
• COBOL User defined functions support including function prototypes
• Code folding

Limitations of COBOL program files

• False unreachable code warnings: In some cases, the editor incorrectly reports that code is unreachable when more than one entry point is present. One such case is reported in this issue. You can use a user setting to disable warnings for unreachable code completely as described in Enabling and disabling unreachable COBOL code warnings.
• Incomplete support for conditional compilation: Our community has reported various issues when programs contain conditional compilation statements. These types of programs are currently not fully supported.
• For COBOL programs that load a large number of copybooks from MVS, downloading can take a long time. Consider as a workaround the user setting "zowe.files.temporaryDownloadsFolder.cleanup": false that will not re-download the files between editing sessions.

Enabled features of COBOL copybook files

• Syntax errors
• Find all references in file
• Peek references in file
• Rename symbol in file
• Outline view
• Syntax highlighting
• Code completion
• Snippets
• Embedded languages support such as SQL, CICS, and DLI

Limitations of COBOL copybook files

• No support for Hover
• No support for Go to declaration
• No support for Find all references across the multiple files
• No support for Peek references across the multiple files
• No support for Rename symbol from a copybook to the files that include it

PL/I

The following lists show the implementation status of the PL/I language server. Use these lists to check that the feature that you are looking for was implemented or is regarded as a known issue. Let us know if you have any additional issues.

Enabled features of PL/I program files

• Syntax highlighting
• Syntax errors
  • Errors are translated for different locales
• Document highlighting
• Hover
• Go to declaration
• Find all references in file and across the multiple files
• Peek references in file and across the multiple files
• Rename symbol in file and across the multiple files
• Outline view
• Code completion
• Include file resolving and include file hover support
• Document link support to open include file by using Ctrl+Click (Windows) or Cmd+Click (Mac)
• Embedded languages support such as SQL, CICS, and DLI
• *process (or %process) compile options statements, such as:
  • *process source MARGINS(2,120);
  • *process SYSTEM(CIS, DB2);
  • *process LIST TEST;
  • Syntax and other supported compiler options can be found in:
    • %PROCESS directive
    • Compile-time option descriptions
• Commenting and uncommenting PL/I code
• Latest Pl/I 6.1 PTF language support, up to and including the January 2024 PTF.
• Embedded Language Support for CICS 6.2 Beta version in PL/I

Limitations of PL/I program files

• No support for macros
• The left margin is currently not fully configurable. The minimum value required is 2.
• PL/I 6.1
  • No support is included for the MAXRUNONIF compiler option.
  • No support is included for the PROCINC directive. An alternative way to accomplish the purpose of the PROCINC directive is to use the PROCESS directive with the compiler option from the data set that you want to add for the PROCINC directive.
• For PL/I programs that load a large number of include files from MVS, downloading can take a long time. Consider as a workaround the user setting "zowe.files.temporaryDownloadsFolder.cleanup": false that will not re-download the files between editing sessions.

The following legal PL/I syntactic constructions are marked as errors:

• Invalid PL/I syntax in macro preprocessor input when the macro preprocessor output is legal PL/I
• Labels on preprocessor directives
• Entry constants
• Type functions
• Factoring of attributes when you declare structures
• An isub option with defined attribute
• A tstack attribute of the attach statement
• Implicit variable declarations

The following invalid PL/I syntactic constructions are not marked as errors:

• Condition prefixes for do statements
• Label prefixes for declare, default, when, otherwise, and on statements
• Scaling factors for float or fixed
• Duplicate attributes for declaration statements
• Syntax errors in macro preprocessor output

Enabled features of PL/I include files

• Syntax errors (lexing and parsing)
• Find all references in file
• Peek references in file
• Rename symbol in file
• Outline view
• Syntax highlighting
• Code completion
• Embedded languages support such as SQL, CICS, and DLI

Limitations of PL/I include files

• No support for showing syntax errors for resolving variables
• No support for Hover
• No support for Go to declaration
• No support for Find all references across the multiple files
• No support for Peek references across the multiple files
• No support for Rename symbol across the multiple files

HLASM

The following lists show the implementation status of the HLASM language server. Use these lists to check that the feature that you are looking for was implemented or is regarded as a known issue. Let us know if you have any additional issues.

Enabled features of HLASM program files

• Syntax highlighting
• Syntax errors, which currently only include the following:
  • Copy statements not resolved
  • Spaces in continuation line
  • Invalid number of operands
• Document highlighting
• Hover on operations and operands
• Go to declaration for all operands, including those from copy members
• Find all references in file
• Peek references in file
• Outline view for macros, CSECTs, and DSECTs
• Code completion, including snippet-style completion for operations and macros
• Copy member file resolving and copy member file hover support
• SYS1.MACLIB Macro remote file resolving and content hover support
  • The z/OS version for SYS1.MACLIB is configurable between 2.4, 2.5, and 3.1 with the user setting "zopeneditor.hlasm.zosMacrosVersion".
• Custom Macro file resolving, code completion, and content hover support for local macros.
• Document link support to open copybook file by using Ctrl+Click (Windows) or Cmd+Click (Mac)
• Quick fix hints for lines that are too long and spaces in the continuation line
• Commenting and uncommenting HLASM code
• Progress tracking for long-running operations

Limitations of HLASM program files

• Limited syntax checks such as no errors for undeclared variables
• Syntax highlighting limitations on multi-line strings
• Syntax highlighting limitations on non-continuation lines that begin at column 16
• Syntax highlighting does not recognize continuation lines that begin at column 17 and later as comments
• Keyword based HLASM code folding: Currently VS Code default code folding is based on indentation levels, not keywords.
• Custom Macro file resolving is not currently available for remote macros.

REXX

The following lists show the implementation status of the REXX language server. Use these lists to check that the feature that you are looking for was implemented or is regarded as a known issue. Let us know if you have any additional issues.

Enabled features of REXX program files

• Syntax highlighting
• Syntax errors
• Hover
  • Keyword hovers are translated for different locales
• Find all references
• Outline view
• Code completion
• Include control directive resolution and hover support
• Syntax Highlighting for Include control directives
• Commenting and uncommenting REXX code

Limitations of REXX program files

• No support for the 'END' keyword as a variable
• No support for embedded languages
• Code Completion and Hover do not support keywords that are not keyword instructions
• Some color themes may not highlight all symbols correctly
• Files that contain the replacement character (�) are not parsed correctly
• The simple symbol, constant symbol, compound symbol, stem, and internal routine suggestions are restricted to the current file in the editor
• Code Completion inserts an extra pair of parenthesis when an existing function call in the editor is replaced with a built-in function
• Changing the contents of a resolved include control directive will not necessarily clear errors
• The language features do not consider the contents of a resolved include control directive
• Keyword based REXX code folding: Currently VS Code default code folding is based on indentation levels, not keywords.

JCL

The following lists show the implementation status of the JCL language server. Use these lists to check that the feature that you are looking for was implemented or is regarded as a known issue. Let us know if you have any additional issues.

Enabled features of JCL program files

• Syntax highlighting
• Syntax errors
• Outline view
• Code completion
• Snippets
• Code folding
• Include file support for file level statements
• On-hover Data Set Name resolution using SET values
• Support for JCL command statements

IBM RSE API Plug-in for Zowe CLI

Known issues and limitations for IBM RSE API Plug-in for Zowe CLI (RSE CLI plug-in)

HTTP protocol support for RSE profiles

As of Zowe CLI 6.31.0, HTTP support is not available for RSE profile connections. There is a Zowe CLI issue that can be tracked for solution to bring this support back.

npm WARN for peer dependencies

When installing RSE CLI plug-in, you may encounter an npm WARN for an unmet peer dependency of Zowe CLI even though you have an accommodating version installed. There is due to a known bug in npm versions prior to 7. Having the warnings will not interfere with the successful installation of the plug-in; however, these warnings can be eliminated by running the command npm install npm@latest -g to obtain the latest version of npm.

RSE CLI plug-in with ZAPP

• When using the --mappings-file tag to state the location of a mappings file to use for upload and download of MVS files, if you have a zapp.json and a zapp.yaml in the same directory, the zapp.yaml will take precedence over the JSON file. It is recommended that you have only one zapp.yaml or zapp.json file when using ZAPP files at a project level.

RSE CLI plug-in with JSON Web Tokens

• JSON Web Tokens are not supported by Zowe Explorer 1.9.0 or previous versions.
• The JWT logout command zowe rse auth logout is not supported by the host component RSE API 1.0.0.
• When using token authentication in Wazi Dev Spaces, the login action will fail if the team configuration profile is opened. To prevent this, make sure that the team configuration file is closed and the "autoSave" setting of editor is set to true.

RSE CLI plug-in TSO and UNIX commands

• The command zowe rse issue command {COMMAND}, which can be used to issue a TSO command, is not supported by the host component RSE API 1.0.0.
• Issuing a UNIX command with an RSE profile via Zowe Explorer is not supported yet.

RSE CLI plug-in COPY DATASETS CROSS LPAR command

• The command zowe rse copy data-set-cross-lpar {COMMAND}, which can be used to copy datasets across lpars, does prompt for entering the username and password of the service twice which actually generates from the zowe cli side, but doesnot specify which LPAR it corresponds to.

Known issues with z/OS UNIX System Services

• z/OS UNIX System Services does not accept the upload of a directory or file names with spaces in them.

• An error occurs when you specify z/OS UNIX System Services paths in a Window's Bash terminal (for example: /u/userid). To solve the issue, create an environment variable MSYS_NO_PATHCONV with a value of 1 in User Variables and restart the terminal.

Using z/OSMF with Z Open Editor and Zowe Explorer

IBM Z Open Editor can download remote files that are included in your programs through the RSE API or z/OSMF. If you are using z/OSMF to download remote files, it is recommended that you configure the host system with the following values at a minimum for z/OSMF:

Parameter	Value
MAXSESSIONS	250
MAXUSERS	25

These recommendations ensure that optimal performance will be maintained even if many users are requesting remote downloads concurrently.

If your development demands typically see more than 25 users requesting remote files concurrently, it is recommended that you increase MAXUSERS to meet your needs and increase MAXSESSIONS to a value equal to MAXUSERS*10.

For more information on where to set these values or solutions if your host system is running into resource problems, see this blog.

Known issues for user build

Using an older version of IBM Dependency Based Build

IBM Z Open Editor v3+ is optimized for working with IBM Dependency Based Build (DBB) v3. However, it can also still work with DBB v2 and v1. To be able run builds with v3 or v2 you need to use the main branch of the https://github.com/IBM/dbb-zappbuild zAppBuild git repository. To build with DBB v1 you must checkout the branch called zAppBuild_2_x. Here the 2 stands for zAppBuild version 2 as the latest version in the main branch of zAppBuild is v3, which is the one that works with DBB v2 and v3.

Using an older version of DBB zAppBuild

If you are not using the latest branches of zAppBuild or have your own fork that was based on an older version than DBB zAppBuild 2.3.0 then consider the following. The encoding of the dependency file generated during an IBM User Build was recently changed from IBM-1047 to a standard UTF-8 encoding. This change means that if the latest version of IBM Z Open Editor is not paired with DBB zAppBuild 2.3.0 or greater you will have to add the previously required IBM-1047 encoding to the dependency file being generated, by adding the following to your .gitattributes file in your project in order to run an IBM User Build successfully:

*.userbuilddependencies zos-working-tree-encoding=ibm-1047 git-encoding=utf-8

Additionally, when using DBB v1 and zAppBuild v2, when you build a program file that contains spaces in the file path or name, you get the following error:

java.util.MissingFormatArgumentException: Format specifier ‘%s’

At the moment, zAppBuild v2 does not support spaces or URI encoded space character %20 in the build file path or name. See the issue Support spaces in build file directory paths for updates.

Other known issues

• Some programs fail building on z/OS with the error Missing required dependency file field 'isCICS'. when using the --dependencyFile ${dependencyFile}" build script arguments in the ZAPP profile. As a workaround remove this parameter for now until we can provide a fix. This parameters is an optional performance improvement. Builds can work without it as well.

Reporting issues

If you want to provide feedback or report an issue, open an issue in the GitHub repository. Any report and feedback is appreciated.